In addition to the named parameters below, this endpoint accepts the
In addition to the named parameters below, this endpoint accepts the following query parameter conventions which are pattern-validated and therefore not declared as named parameters:
- filters.<field>[<op>] — content filtering (documented below).
- select.<bucket>[<op>] — data projection (documented below).
Content filtering (filters.*)
Filtering narrows list results to compositions matching field values. The allowed field names are project-specific — they come from the project's component definitions — which is why filters.* parameters are pattern-validated rather than declared as named parameters.
Syntax: filters.<field>[<operator>]=<value>. <field> is one of:
- A system field: name, slug, type, created, modified, entityId, editionId, releaseId, patternId, creator, creatorSubject, author, authorSubject, projectMapId, projectMapNodeId, workflowId, workflowStageId, categoryId, labels, labelGroups, uiStatus, or locale.
- A component parameter, addressed as parameters.<parameterId>. Filtering by parameters requires also filtering to a single composition type (e.g. filters.type[eq]=...).
- A sub-property of a parameter for certain parameter types: content references (parameters.<id>.slug|name|type), links (parameters.<id>.type|projectMapNodeId), and assets (parameters.<id>.url|title|description|mediaType).
| Operator | Effect |
|---|---|
| [eq] / [neq] | Exact equality / inequality. |
| [match] | Contains (text search) match; text-like fields only. |
| [starts] | Prefix match. Value limited to letters, numbers, _, ., -, and spaces. |
| [lt] / [lte] / [gt] / [gte] | Comparisons for number, date, and datetime fields (including created / modified). |
| [in] / [nin] | Comma-separated list; matches any (OR) / none of the values. |
| [all] | Comma-separated list; list-valued fields (e.g. labels, multi-selects) must contain every value (AND). |
| [def] | true or false; whether the field has a value at all. |
Behavior:
- Values are single strings, or comma-separated lists for [in], [nin], and [all]. Dates accept YYYY-MM-DD or a full datetime string. An empty value is rejected — use [def] to test presence.
- Not every operator is valid for every field; the allowed set depends on the field's type. An unsupported combination returns HTTP 400 with the supported operators listed.
- Malformed keys, unknown operators, and unknown field names return HTTP 400.
- Filters match root compositions only.
Examples:
- filters.type[eq]=landingPage — only compositions of type landingPage.
- filters.modified[gte]=2026-01-01 — modified this year.
- filters.type[eq]=landingPage&filters.parameters.audience[in]=b2b,b2c — parameter filter scoped to one type.
- filters.labels[all]=approved,featured — has both labels.
Data projection (select.*)
Projection returns a subset of the response by pruning fields (parameters), field types, and slots before values are resolved. The allowed names are project-specific — they come from the project's component definitions and content types — which is why select.* parameters are pattern-validated rather than declared as named parameters.
Syntax: select.<bucket>[<operator>]=<value>. Values are comma-separated lists of names. * is the only wildcard and matches zero or more characters (e.g. seo_*).
| Parameter | Effect |
|---|---|
| select.fields[only]=a,b | Keep only the named fields/parameters; drop everything else. |
| select.fields[except]=a,b | Drop the named fields/parameters; keep everything else. |
| select.fields[locales]=a,b | For the named fields that survive filtering, return the full per-locale value map instead of only the requested locale's value. |
| select.fields[blockDepth]=N | Limit how many levels of block field children are kept. 0 removes all block fields; preserveAll prevents projection from trimming fields inside block children. |
| select.fieldTypes[only]=a,b | Keep only fields of the named types (type IDs such as text, richText, asset). |
| select.fieldTypes[except]=a,b | Drop fields of the named types. |
| select.slots[only]=a,b | Keep only the named slots. |
| select.slots[except]=a,b | Drop the named slots. |
| select.slots[depth]=N | Limit how many levels of nested components are kept in slots. |
| select.slots.<name>[depth]=N | Depth limit for one specific slot; overrides slots[depth]. |
Behavior:
- Projection applies recursively at every component and block in the returned tree, and is forwarded into entries resolved through reference fields.
- When operators combine, all [only] sets are intersected first, then [except] sets are subtracted — exclusion always wins.
- Unknown field, slot, or type names are silent no-ops (the tree shape is preserved; non-matching content is simply absent). Unknown operators return HTTP 400.
- An empty list (select.fields[only]= or select.slots[only]=) strips every member of that bucket; [except]=* is equivalent.
- [depth] counts nesting within a single fetched tree and resets inside referenced entries.
Examples:
- select.fields[only]=title,slug — keep only titles and slugs, everywhere in the tree.
- select.fieldTypes[except]=richText — everything except rich-text fields.
- select.fields[only]=title&select.slots[only]= — root title only, with all slots flattened.
- select.slots[depth]=2&select.fields[only]=label,url — two levels of nested components, trimmed to label and url.
Request
- Base URL: https://uniform.app
- URL: https://uniform.app/api/v1/canvas
- Auth: one of:
- API key in header x-api-key
- HTTP bearer
Query parameters
Specify a single composition ID to fetch. The response will be a single composition. This is a primary query parameter and cannot be used with any other primary query parameters. When editions=raw, this parameter matches on composition or edition IDs and edition resolution is disabled.
Specify a single component ID to fetch the component's composition defaults. The response will be a single composition. This is a primary query parameter and cannot be used with any other primary query parameters
Specify a historical composition version ID to fetch (retrieved from the canvas-history API). Must be used with the compositionId parameter
Specify multiple composition IDs to fetch. The response type will be a list. This is a primary query parameter and cannot be used with any other primary query parameters. When editions=raw, this parameter matches on composition or edition IDs and edition resolution is disabled.
Filters composition lists by the user who created them. The user is specified by their identity subject. This is a list query parameter and cannot be used with any primary query parameters
Matches compositions where their name, slug, or definition name contains the specified keyword. NOT a full-text search; does not match composition contents. This is a list query parameter and cannot be used with any primary query parameters
Maximum number of records to return This is a list query parameter and cannot be used with any primary query parameters
Number of records to skip This is a list query parameter and cannot be used with any primary query parameters
Sets the sorting of the results. If unspecified, results are sorted by name ascending. Allowed values are: updated_at_DESC, updated_at_ASC, created_at_DESC, created_at_ASC, name_DESC, name_ASC, slug_DESC, slug_ASC. When using primary query parameters, this parameter is ignored
Returns counts for distinct values of the specified field or fields (provided as comma-separated IDs).
Matches compositions based on whether they are a pattern composition or a regular composition. If true, only pattern compositions will be returned. If false, only regular compositions will be returned. If omitted or 'any', both pattern and regular compositions will be returned. This is a list query parameter and cannot be used with any primary query parameters
This specifies which type of patterns to return. This query parameter has no effect when pattern is false.
- all - Returns all pattern instances
- component - Returns only component patterns
- composition - Returns only composition patterns
Includes the patternType attribute in the response
The project the composition(s) belong to
Specify a project map ID to fetch by path or node ID from. If not specified, the default project map for the projectId is used. Only used when fetching by projectMapNodeId or projectMapNodePath
Specify a single composition to fetch by associated project map node ID. The response will be a single composition. This is a primary query parameter and cannot be used with any other primary query parameters
Specify a single composition to fetch by associated project map node path. The response will be a single composition. This is a primary query parameter and cannot be used with any other primary query parameters
Signals an enhancer proxy to skip processing enhancements to the data and return raw data only. This improves performance if you do not require enhanced component data. If calling the Canvas API directly with no enhancer proxy, this has no effect
If true, any pattern references in the composition will be left unresolved. This is appropriate if you intend to serialize the composition without patterns embedded into it, and serialize the pattern data separately. Default: true when format is canonical. False otherwise. Prefer selecting a format rather than using this option.
This parameter is unused and has no effect. Passing this parameter will become an error in the future
If true, any pattern override data is not resolved by the API. This is intended for internal use in the Canvas editor and should not be used. Passing this parameter automatically implies withComponentIDs is true. Default: true when format is canonical or editor. False otherwise. Prefer selecting a format rather than using this option.
Specify a single composition to fetch by slug. The response will be a single composition. This is a primary query parameter and cannot be used with any other primary query parameters
Filtration by category ID. An empty string can be used to include records without a category.
Publishing state to fetch. 0 = draft, 64 = published. This is a list query parameter and cannot be used with any primary query parameters
The component type (by public ID) to filter by. Note that this filters the root composition type only; components in slots are not matched by this filter. This is a list query parameter and cannot be used with any primary query parameters
Filters composition lists by the UI status of the composition. This internal status is subject to change without notice and is thus marked deprecated to discourage use of internal data. This is a list query parameter and cannot be used with any primary query parameters
Filters out compositions without attached node or filters out compositions with attached nodes if set to false. If not specified, no filtration is applied. This is a list query parameter and cannot be used with any primary query parameters
Filters composition lists by the user who last updated them. The user is specified by their identity subject. This is a list query parameter and cannot be used with any primary query parameters
If true, the _id unique identifier of each non-root component will be part of the response data. If false, the _id will not be present in the API response. Note: the default value depends on the format: true for editor or canonical, false for delivery or when no format is specified. Prefer selecting a format rather than using this option.
Controls whether the total count of results will be returned along with the current results page in a list. Has no effect when not fetching a list. This does impact performance when enabled
Returns the UI status string of the composition. This internal status is subject to change without notice and is thus marked deprecated to discourage use of internal data
Returns the definition of any attached workflow along with the composition data
Includes project map node information in the composition results
Has no effect.
One or more locales to filter and localize by. For list responses, only compositions that enable one of the specified locales or enable no locales will be returned. When more than one locale is passed, the list matches with an OR on each locale. For all types of response, the response will be localized to include only the first matching locale's data.
This parameter accepts a single value, a comma-delimited list of values, or the Accept-Language header syntax. Examples: en-US fr-CA,fr de-AT;q=0.9,de-DE;q=0.8,en;q=0.7
When this parameter is not passed, all locales' data will be returned. If a composition is requested by ID and does not possess any of the specified locales, HTTP 404 will be returned
The ID of a release to fetch the content for.
- When unspecified, all release content is excluded from the result(s).
- When specified, all content is returned as it would appear in the release if it was released now. This includes both content copied to the release and changed, as well as content that is not part of the release.
Content copied to a release can be differentiated from base content by the releaseId property on the content. If the content is not copied to the release, this property will be null
Search on textual fields of a composition. Matches against fully rendered content including resolved pattern content. Use this for "where does this content appear" queries. Note: For long text fields, the tail of the text is not guaranteed to be searchable. Example: ?search=hello
BETA: Semantic search using vector similarity to find content by meaning. Matches against source content only - pattern base content matches the pattern itself, not consumers. Use this for "where is this content defined" queries. Requires AI credits.
Controls the edition resolution behavior.
auto: (default) Editions are evaluated automatically and the best matching edition is returned. When a locale is provided, the edition with the highest priority that enables that locale matches Without a locale, the default edition is matched
all: Every edition is returned as a separate row. Note: this has no effect when used with compositionId which always returns a single result.
raw: the compositionId and compositionIDs parameters target exact edition/composition IDs and no edition resolution is performed. compositionId or compositionIDs MUST be provided with this option. If versionId is passed, this is always enabled.
Specify a format you want the results in. Any explicit shaping flag (skipPatternResolution, skipOverridesResolution, withComponentIDs) overrides this alias.
- canonical: PUT-safe structure — patterns and overrides left unresolved and component _ids included. This is the format the Uniform CLI uses when syncing. (skipPatternResolution=true, skipOverridesResolution=true, withComponentIDs=true).
- editor: For loading into a Uniform editor - same as canonical, but with patterns expanded (skipPatternResolution=false). Still PUT-safe — the PUT ignores the expanded pattern nodes.
- delivery: default structure for serving to a frontend — patterns and overrides resolved and component _ids removed.
Controls filtering of trashed items.
exclude: (default) Only return items not in trash. only: Only return trashed items (for trash view). include: Return both trashed and non-trashed items.
Response
OK
Changes
No recorded changes to this operation across all 1 revision of this API.