Skip to main content

Query Tenant Content

GET 
/tenants/:tid/q/query

Query published content versions belonging a tenant.

The following query parameters allow customizing the listing.

Sorting​

Sorting Examples

?sort_by=name
  &sort_descending=true

?sort_by=slug
  • Query param sort_by: the name of content query fields to sort on. Only a single sort field is supported. If omitted, contents are sorted on creation date.
  • Query param sort_descending: false for ascending sort order, true for descending sort order. Default: false (ascending)

Filtering​

Filtering Examples

Examples:
?filter=tag:eq:feature%20film

?filter=tag:eq:action
  &filter=created_block_time:ge:2023-01-01
  • Query param filter: a content field name separated with a comparator from the value to match. Multiple instances allowed.

Field Names:

  • tag a content tag
  • group a content group
  • unique_group.id a unique group's id
  • unique_group.type a unique group's type
  • lib (alias library) the library ID of the content; only supports :eq:, :in:, :ni:
  • created_block_time the version's creation time in ISO 8601 format, e.g. 2006-01-02T15:04:05.000Z07:00 or 2006-01-02
  • any other name is treated as a query field name and matched against the indexed query fields of each content object (see Query Fields) - except for a name that is a near-miss of a reserved field above (tags, groups, unique_group, unique_groups, libraries, created_block_number), which returns a 400 error instead of silently matching nothing; use the qf. prefix below to filter on a query field with one of those names.

To filter on a query field whose name collides with a reserved field above (e.g. a query field literally named tag), prefix the name with qf.:

?filter=qf.tag:eq:my-custom-value

The qf. prefix is stripped before lookup and is otherwise identical to an unprefixed query field filter.

Comparators:

  • ::, :co: contains
  • :nc: not contains
  • :eq: equals
  • :ne: not equals
  • :lt: less than
  • :le: less than or equal
  • :gt: greater than
  • :ge: greater than or equal. Use with an empty string to denote "not empty", e.g. tag:ge:
  • :in: value is any of a comma-separated list, e.g. tag:in:4K,HDR,8K
  • :ni: value is none of a comma-separated list

Notes:

  • values MUST be percent-encoded.
  • metadata paths SHOULD be percent-encoded as well (even though the URI "query" string specifically allows forward slashes /)
  • :in:/:ni: values have no escaping mechanism for a literal comma - the value is always split on ,

Additional Filtering​

Additional Filtering Examples

?latest_version_only=false
  • Query param latest_version_only: tag without value or bool to retrieve only the latest content version per content ID. Default: true. This endpoint only indexes latest-version data, so false returns a 400 error.

Including Relational Data​

Include Examples

?include=fields

?include=tags
  &include=fields

?include=tags,groups

?include=all

?include=none
  • Query param include: controls which indexed relational data is returned alongside each result. Accepted values (case-insensitive, repeatable or comma-separated): fields (query fields, the default), tags, groups, uniquegroups, all, none. An unrecognised value returns HTTP 400.

The default behaviour when include is absent is equivalent to ?include=fields — only query fields are returned. Pass ?include=all to receive tags, groups, unique groups, and query fields in a single request. Pass ?include=none to suppress all relational data, including the default query fields.

Selection​

Selection Examples

?select=/public

?select=/public/name
  &select=/public/description
  &select=/public/thumbnail

Query param select: path of metadata subtree to return. If the query parameter is specified multiple times, the results of each expression are merged. If not specified, no meta data is returned.

Removal​

Removal Examples

?remove=/public/description

?select=/public
  &remove=/public/description
  &remove=/public/thumbnail

Query param remove: path of metadata subtree to remove from the result. May be specified multiple times.

Paging​

Paging Examples

?start=20
  &limit=10
  • Query param start: index of the first content object to retrieve. Leave empty to retrieve the first content.
  • Query param limit: integer specifying the number of contents to return. Default: 100.

Request​

Responses​

The list of contents.