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

Name	Type	Description
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

200

// 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:

Filters