Search and filter
The list methods of the Content API clients and the AssetClient accept filters, a keyword search, and a sort order. They use the same search index as the search and filter bar in the Uniform dashboard. What you can find in a listing, you can also find from code. The API supports a few filters the bar doesn't, such as asset and link fields and their sub-properties.
Choosing a client#
Patterns don't have their own endpoints. You list them with the entry or composition clients and the pattern and patternType options.
| Content | Client and method | Options | Endpoint |
|---|---|---|---|
| Entries | EntryDeliveryClient.list, EntryManagementClient.list | pattern: false (default) | /api/v1/entries |
| Entry patterns | EntryDeliveryClient.list, EntryManagementClient.list | pattern: true | /api/v1/entries |
| Compositions | CompositionDeliveryClient.list, CompositionManagementClient.list | pattern: false | /api/v1/canvas |
| Composition patterns | CompositionDeliveryClient.list, CompositionManagementClient.list | pattern: true, patternType: 'composition' | /api/v1/canvas |
| Component patterns | CompositionDeliveryClient.list, CompositionManagementClient.list | pattern: true, patternType: 'component' | /api/v1/canvas |
| Assets | AssetClient.list from @uniformdev/assets | none | /api/v1/assets |
CompositionDeliveryClient calls the edge counterpart, /api/v1/compositions, which forwards filters to /api/v1/canvas. The composition clients return compositions and patterns together when you omit pattern. The entry clients return only regular entries unless you set pattern: true or pattern: 'any'.
Delivery clients read from the edge and default to published content. Management clients read from the origin and default to draft content. Both accept the same filters, and you can set state to choose draft or published. Assets are available only through the management API. They're returned in their published state and have no locales or editions.
Filter syntax#
Pass filters as an object. Each key is a field, and each value is an object with one operator and its value:
To apply two operators to the same field, put the operator in the key instead:
The client serializes filters into filters.<field>[<operator>]=<value> query parameters. List values are joined with commas. You can call the REST API directly with the same syntax. Send the request to the Uniform API host for your region, with an API key in the x-api-key header:
An entry, composition, or asset must match every filter to be returned.
Operators#
| Operator | Matches | UI equivalent |
|---|---|---|
eq / neq | Exact equality / inequality | is / is not |
match | Contains the text. Text-like fields only. | contains |
starts | Starts with the text. The value can contain only letters, numbers, _, ., -, and spaces. | starts with |
lt / lte / gt / gte | Less than / less than or equal to / greater than / greater than or equal to. Number, date, and date/time fields, including created and modified. | is before, is after, less than, greater than, and similar |
in / nin | Any of / none of a list of values | is any of / is none of |
all | List-valued fields, such as labels and multi-select fields, contain every value in the list | is all of |
def | true if the field has a value, false if it doesn't | is not empty / is empty |
The API has no between operator. Combine gte and lte on the same field instead. Dates accept YYYY-MM-DD or a full ISO 8601 date and time. An empty value is rejected, so use def: false to find items without a value.
Not every operator works on every field. An unsupported operator, an unknown field, or a malformed key returns HTTP 400. For an unsupported operator, the message lists the operators the field supports.
System fields#
System fields apply to every item, regardless of its type.
| Field | Operators | Available on |
|---|---|---|
entityId | eq, neq, in, nin | All |
type | eq, neq, in, nin | All. The content type, composition type, component type, or asset type. |
name, slug | match, starts, eq, neq, in, nin, def | All. Assets have name only. |
created, modified | eq, neq, lt, lte, gt, gte, in, nin | All |
creator, author | match, starts, eq, neq, in, nin | All. The name of the user who created or last modified the item. |
creatorSubject, authorSubject | eq, neq, in, nin | All. The user ID of the creator or last modifier. |
categoryId | eq, neq, in, nin, def | Compositions and patterns |
labels, labelGroups | eq, neq, in, nin, all, def | Assets |
uiStatus | eq, neq, in, nin | Entries, compositions, and patterns. Values: draft, modified, published. |
locale | eq, neq, in, nin | Entries, compositions, and patterns. Matches items that have the locale enabled. |
workflowId, workflowStageId | eq, neq, in, nin, def | Entries, compositions, and patterns |
patternId | eq, neq, in, nin, def | Entries, compositions, and patterns |
editionId, releaseId | eq, neq, in, nin, def | Entries, compositions, and patterns |
projectMapId, projectMapNodeId | eq, neq, in, nin, def | Compositions and patterns |
type, uiStatus, and locale can each be used only once per request.
Field and parameter filters#
Address custom fields with a prefix:
- Entries and entry patterns:
fields.<fieldId> - Compositions and composition or component patterns:
parameters.<parameterId>. Only the root component's parameters are matched. - Assets:
fields.<fieldId>
Entries, compositions, and patterns need a filter to a single type before you can filter or sort by a field, for example type: { eq: 'article' }. Without one, the API returns HTTP 400. Asset filters don't have this requirement, unless the same field ID has different types across asset types. Sorting by an asset field still needs a filter to a single asset type.
| Field type | Operators |
|---|---|
| Text, single select | match, starts, eq, neq, in, nin, def |
| Multi select | eq, neq, in, nin, all, def |
| Rich text | match, starts, def |
| Number, date, date/time | eq, neq, lt, lte, gt, gte, in, nin, def |
| Boolean | eq, neq, def |
| Reference (entries only), by referenced entry ID | eq, neq, in, nin, def |
| Asset, by asset ID | eq, neq, in, nin, def |
| Link, by path | match, starts, eq, neq, in, nin, def |
Blocks, enrichment, JSON data, and image URL fields can't be filtered.
Reference, asset, and link sub-properties#
Reference fields on entries, and asset and link fields, can also be filtered by a system property of the item they point to. For example, filter a reference field by the referenced entry's name or slug. Add the property to the field path:
| Field type | Sub-property | Operators |
|---|---|---|
| Reference | .name, .slug | match, starts, eq, neq, in, nin, def |
| Reference | .type, .uiStatus | eq, neq, in, nin, def |
| Asset | .url, .title, .description | match, starts, eq, neq, in, nin, def |
| Asset | .mediaType | eq, neq, in, nin, def |
| Link | .type, .projectMapNodeId | eq, neq, in, nin, def |
You can't filter by the custom fields of a referenced entry, or through more than one level of references.
Asset properties#
Every asset has these filterable properties in addition to the fields of its asset type:
| Property | Type |
|---|---|
fields.title, fields.description, fields.url, fields.mediaType | Text |
fields.size (bytes), fields.width, fields.height (pixels) | Number |
Keyword search#
Pass search to run a full-text search. It matches the name, slug, and ID of an item and the values of its text-like fields. This includes content from resolved patterns and connected external data. Search tolerates small typos. The tail of very long text values isn't guaranteed to be searchable.
Combine search with filters to narrow the results. Sort by relevance_DESC to return the best matches first.
On assets, use keyword instead of search. It runs the same full-text search against the asset's title and description.
note
The entry and composition endpoints also accept keyword, an older match that doesn't use the search index. On compositions it matches only the name, slug, and type. Use search for new code.
Sorting#
Pass one sort field in orderBy, formatted as <field>_ASC or <field>_DESC:
created_at,updated_at,name,slugcreator,author- A field or parameter of a single selected type, for example
fields.price_ASC. Rich text and multi-select fields can't be sorted on. relevance, whilesearchis set- On assets filtered to a single asset type, also
fields.size,fields.width, andfields.height
The default order is updated_at_DESC for entries, name_ASC for compositions and patterns, and created_at_ASC for assets. Passing more than one sort field returns HTTP 400.
Pagination and total count#
Use limit and offset to page through results, and withTotalCount: true to get the total number of matches in totalCount. When a request uses search, filters, or a sort on anything other than name, slug, or dates, limit can be at most 100.
Locales and editions#
The locale option controls which locale the results are resolved to and which locale's field values filters and search match. It also limits results to items that enable that locale or enable no locales. Without locale, filters and search match values in any locale.
The locale filter works differently: filters: { locale: { eq: 'de-DE' } } returns items that have that locale enabled.
On entries and compositions, editions: 'auto' (the default) returns the best-matching edition of each item for the requested locale. editions: 'all' returns every edition as its own result.
Examples#
Compositions by parameter value#
Component patterns modified this year#
Assets#
Label filters take label public IDs.
Limitations#
- Filters are always combined with
AND. There is noORacross fields. To match several values of one field, usein. - Composition and pattern filters match root component parameters only, and entry filters can't reach fields inside blocks.
- Exact-match filter values can be at most 255 characters. Text is indexed up to about 10,000 characters per field.
- Search, filters, and custom sorting aren't available for items in Trash. Combining them with
deleted: 'only'ordeleted: 'include'returns HTTP 400.
Related#
- Search, filter, and sort: the search and filter bar in the Uniform dashboard
- Content API clients: the delivery and management clients
- Entries endpoint OpenAPI specification