Filters

Apply one or multiple filters for list endpoints like All Documents and Document Collections. Each filter parameter refers to one field.

Filters can be submitted per URL with brackets or as URI Encoded JSON Object. Check out the examples page to see how it's done.

Filter documents

GET https://api.cmft.io/v1/<repoName>/<endpoint>?filters[0][*.<fields|meta>.<fieldName>][operator]=<value>

Path Parameters

NameTypeDescription

repoName

string

The API identifier of the repository

endpoint

string

The endpoint you'd like to request

filter

string

Provide a filter with square brackets or as URI Encoded JSON Object

// Example: Filter by contenType 'poem'
"data": [
    {
      "fields": {
        "title": "Roses are red"
      },
      "meta": {
        "id": "314159265358979323",
        "contentType": "poem",
        "repository": "314159265358979323",
        "revision": 1,
        "tags": [],
        "createdAt": "2018-01-01T00:00:00.000Z",
        "updatedAt": "2018-01-01T00:00:00.000Z"
      }
    },
    {
      "fields": {
        "title": "Violets are blue"
      },
      "meta": {
        "id": "314159265358979323",
        "contentType": "poem",
        "repository": "314159265358979323",
        "revision": 1,
        "tags": [],
        "createdAt": "2018-01-01T00:00:00.000Z",
        "updatedAt": "2018-01-01T00:00:00.000Z"
      }
    }
]

Filter Types

Field Values

Parameter Name

Description

filters

Filter which documents are returned in a query by checking the value with a relational operator.

Notation

filters[0][*.<fields|meta>.<fieldName>][operator]=<value>

Apply a filter to multiple content types with a wildcard (*):

*.<fields|meta>.<fieldName>

Or refer to a single document type using the following notation:

<contentType>.<fields|meta>.<fieldName>

Basic Example

filters[0][*.fields.category][equal]=spaceships

Or as JSON Object:

"filters": [
  {
    "*.fields.category": {
        "equal": "spaceships"
      }
  }
]

For more examples, have a look at the filters examples page.

Filters for nested fields When applying filters for fields nested in sections, you'll have to omit the section property key. The path for the filter would be *.fields.myField, instead of *.fields.mySection.myField

Include Tags

Decide if a document is included in a list by checking its tags.

Parameter Name

Description

includeTags

One of the tags must match for a document.

Notation

includeTags=<tag1>,<tag2>

Exclude Tags

If a document has one of the stated tags, it will not be included in a response.

Parameter Name

Description

excludeTags

Document will not be included if it has one of the stated tags.

Notation

excludeTags=<tag1>,<tag2>

Relational Operators

Use Relational Operators to evaluate a fields value. Here is a reference for the available operators:

Notation

Convention

Explanation

equal

equal

Validates true for a matching value

notEqual

not equal

Validates true for non-matching values

greaterThan

greater than

Validates true if the field value is greater than the specified value

greaterThanEqual

greater or equal to

Validates true if the field value is greater or equal to the specified value

lessThan

less than

Validates true if the field value is lower than the specified value

lessThanEqual

less or equal to

Validates true if the field value is lower or equal to the specified value

like

like

Validates true if a field value matches. Possible usage: startsWith%, %endsWith, %contains%

notLike

not like

Validates true if a field value does not match. Possible usage: startsWith%, %endsWith, %contains%

empty

empty

Validates true if the field value is empty

notEmpty

not empty

Validates true if the field value is not empty

in

in

Validates true if a value exists in an array

notIn

not in

Validates true if a value does not exists in an array

Logical Operators

Use Logical Operators to connect filters. Available operators are:

  • AND

  • OR

Query String Notation

filters[0][*.fields.category][equal]=spaceships&filters[1][and][*.fields.color][equal]=red

JSON Notation

"filters": [
  {
    "*.fields.category": {
        "equal": "spaceships"
      }
  },
  {
    "and": {
      "*.fields.color": {
        "equal": "red"
      }
    }
  },
  {
    "or": {
      "*.meta.id": {
        "equal": "314159265358979323"
      }
    }
  }
]

Limitations

Filters are currently not available for relation fields. This feature is planned and we will update the documentation as soon as it lands.

Examples

Find some examples on the filters example page:

pageFilters

Last updated