Content Client SDK

The Content Client (ContentClient from @uniformdev/canvas) provides programmatic access to headless content entries stored in Uniform. Use it for server-side data fetching, search indexing, custom API routes, or any scenario where you need to query content outside of the standard composition rendering pipeline.

note

Within the App Router SDK's composition rendering flow, content is resolved automatically. The Content Client is for use cases where you need to access content directly -- such as building sitemaps, search indexes, custom API endpoints, or fetching content that isn't part of a composition.

The Content Client is part of the @uniformdev/canvas package:

npm install @uniformdev/canvas
import { ContentClient } from "@uniformdev/canvas"; const contentClient = new ContentClient({ apiKey: process.env.UNIFORM_API_KEY, apiHost: process.env.UNIFORM_CLI_BASE_URL || "https://uniform.global", projectId: process.env.UNIFORM_PROJECT_ID, });

The App Router SDK does not provide a pre-configured Content Client factory; initialize the client directly as shown above. For composition access, the App Router SDK provides a pre-configured Canvas Client.

Get entries by content type#

const response = await contentClient.getEntries({ type: "blogPost", }); // response.entries is an array of content entries for (const entry of response.entries) { console.log(entry.entry.name, entry.entry.fields); }
const response = await contentClient.getEntries({ type: "blogPost", limit: 20, offset: 0, }); console.log(`Total entries: ${response.totalCount}`);

The Content Client supports advanced filtering using a structured query syntax. Filters are passed as key-value pairs where the key includes the field path and operator.

filters.<field>[<operator>]=<value>
  • field: The field to filter by. Use type for content type, fields.<fieldName> for custom fields, or system properties like name, slug, created, modified.
  • operator: The comparison operator.
  • value: The literal value to compare against.

Example: filter by content type and field value#

const response = await contentClient.getEntries({ filters: { "type[eq]": "brand", "fields.brandName[match]": "adidas", }, });
OperatorDescription
eqEquals
neqNot equal
matchContains (text search) match
startsStarts with. Value limited to letters, numbers, _, ., -, and spaces
lt / lteLess than / less than or equal to
gt / gteGreater than / greater than or equal to
inMatches any value in a comma-separated list (OR)
ninDoes not match any value in a list
allList-valued fields must contain every value in a comma-separated list (AND)
deftrue or false; whether the field has a value at all

Not every operator is valid for every field; the allowed set depends on the field's type. An unsupported combination returns a 400 error listing the supported operators.

Entry metadata#

FieldSupported operators
entityId, type, uiStatus, locale, creatorSubject, authorSubjecteq, neq, in, nin
editionId, releaseId, patternId, workflowId, workflowStageId, categoryIdeq, neq, in, nin, def
created, modifiedeq, neq, lt, lte, gt, gte, in, nin
name, slugmatch, starts, eq, neq, in, nin, def
creator, authormatch, starts, eq, neq, in, nin

Content fields (fields.*)#

Field typeSupported operators
Text, selectmatch, starts, eq, neq, in, nin, def
Number, date, datetimeeq, neq, lt, lte, gt, gte, in, nin, def
Checkboxeq, neq, def
Multi-selecteq, neq, in, nin, all, def
Rich textmatch, starts, def
Reference, asset (by ID)eq, neq, in, nin, def

Reference, asset, and link fields can also be filtered by sub-properties of the item they point to (for example fields.speaker.slug). Text-valued sub-properties take the text operators; ID-valued sub-properties take the same operators as reference fields:

Sub-propertySupported operators
Reference .name, .slug; asset .url, .title, .description; link pathmatch, starts, eq, neq, in, nin, def
Reference .type; link .type, .projectMapNodeId; asset .mediaTypeeq, neq, in, nin, def

For reference fields, you can filter by the referenced entry's properties:

const response = await contentClient.getEntries({ filters: { "type[eq]": "eventSession", "fields.speaker.slug[eq]": "jane-doe", }, });

Filterable reference properties: name, slug, uiStatus, type.

Combine multiple filters to narrow results:

const response = await contentClient.getEntries({ filters: { "type[eq]": "product", "fields.category[eq]": "electronics", "fields.price[gte]": 50, "fields.price[lte]": 500, }, });

The select option fetches a subset of each entry instead of the whole thing. The API prunes fields, field types, and slots before values are resolved, so pruned content skips asset resolution, rich text reference expansion, and data resource fetches -- reducing both payload size and response time.

select accepts a ProjectionSpec object, which the client serializes into select.* query parameters (mirroring the filters.* syntax). The full wire-level projection syntax is documented in the entries endpoint OpenAPI specification.

const response = await contentClient.getEntries({ filters: { "type[eq]": "article" }, select: { fields: { only: ["title", "coverImage"] }, }, });

Every article in the response contains only its title and coverImage fields; everything else -- body, metadata, tags, author references -- is absent.

A projection spec has three buckets:

BucketSelects byExample
fieldsField namefields: { only: ["title", "slug"] }
fieldTypesField type ID (e.g. text, richText, asset)fieldTypes: { except: ["richText"] }
slotsSlot name (compositions only)slots: { only: ["hero"] }
OperatorTypeDescription
onlystring[]Keep only fields whose name matches one of these patterns
exceptstring[]Drop fields whose name matches one of these patterns
localesstring[]For matching fields that survive filtering, return the full per-locale value map instead of only the requested locale's value
blockDepthnumber | "preserveAll"Limit how many levels of block field children are kept. 0 removes all block fields; "preserveAll" prevents projection from trimming fields inside block children
OperatorTypeDescription
onlystring[]Keep only fields of the named types
exceptstring[]Drop fields of the named types
OperatorTypeDescription
onlystring[]Keep only the named slots
exceptstring[]Drop the named slots
depthnumberLimit how many levels of nested components are kept
named{ [slotName]: { depth } }Per-slot depth caps; override the container-wide depth for that slot
  • Wildcards: values accept a single * wildcard matching zero or more characters -- seo_*, *Title, and meta*Published are all legal.
  • Recursive by default: projection applies at every component and block in the returned tree, not just the root, and is forwarded into entries resolved through reference fields.
  • Exclusion wins: when operators combine, all only sets are intersected first, then except sets are subtracted. If rules contradict, the exclusion applies.
  • Unknown names are silent no-ops: asking for a field a node doesn't have produces an empty field bag, not an error. The tree shape is preserved; non-matching content is simply absent.
  • Empty only strips everything: fields: { only: [] } removes every field; slots: { only: [] } flattens the component tree. except: ["*"] is equivalent.
  • Depth resets across references: depth and blockDepth count nesting within a single fetched tree and reset inside referenced entries.

Example: strip rich text everywhere#

Drop rich text fields you can't render, without needing to know their names -- including inside entries resolved through reference fields:

const response = await contentClient.getEntries({ filters: { "type[eq]": "article" }, select: { fieldTypes: { except: ["richText"] }, }, });

Fetch a lean payload but keep every locale's value on the slug field:

const response = await contentClient.getEntries({ filters: { "type[eq]": "article" }, select: { fields: { only: ["title", "slug"], locales: ["slug"] }, }, });

The select option is also available on CanvasClient.getCompositionList (where the slots bucket controls the component tree) and on RouteClient.getRoute.

The Canvas Client supports the same filter and projection syntax for compositions, with parameters in place of fields.

A common use case for the Content Client is building a search index. Here is a pattern that retrieves all compositions via the project map and the Route Client, then extracts text content for indexing:

import { RouteClient } from "@uniformdev/canvas"; import { ProjectMapClient } from "@uniformdev/project-map"; const projectMapClient = new ProjectMapClient({ apiKey: process.env.UNIFORM_API_KEY, projectId: process.env.UNIFORM_PROJECT_ID, }); const routeClient = new RouteClient({ apiKey: process.env.UNIFORM_API_KEY, projectId: process.env.UNIFORM_PROJECT_ID, edgeApiHost: "https://uniform.global", }); async function buildSearchIndex() { // 1. Get all project map nodes with compositions const { nodes } = await projectMapClient.getNodes({ projectMapId: "your-project-map-id", }); const compositionNodes = (nodes ?? []).filter((node) => node.compositionId); // 2. Fetch each composition and extract text const indexData = await Promise.all( compositionNodes.map(async (node) => { const route = await routeClient.getRoute({ path: node.path, projectMapId: "your-project-map-id", state: 0, // published state }); if (route.type !== "composition") return null; const { composition } = route.compositionApiResponse; const title = composition.parameters?.pageTitle?.value as string; return { path: node.path, title, compositionId: node.compositionId, }; }) ); return indexData.filter(Boolean); }

note

For large sites, consider running index rebuilds outside the Next.js build process to avoid build timeout limits. You can trigger rebuilds via a webhook when content is published.

  • Nested object search is not supported: You cannot filter by a parameter of a component within a composition, or by a field of a block within an entry.
  • Faceting is available for numeric and short text fields, but requires specifying a single content type filter.
ExportPackageDescription
ContentClient@uniformdev/canvasClient for fetching content entries
CanvasClient@uniformdev/canvasClient for fetching compositions
RouteClient@uniformdev/canvasClient for route resolution
ProjectionSpec@uniformdev/canvasType for the select data projection option
Last modified
Next
Route Client SDK