Skip to content

Reading content from outside

Every content read gates on the row's own site: below an editor of that site you get published rows only, and a hidden row answers 404 like a wrong id.

Content reads need no credential by default, and a credential changes the answer only through its role on the row's site and any read grants, not by being sent: a caller below an editor of that site sees published rows and nothing else — see API keys: scopes are a role ceiling. Two more gates run on every read. A row outside its display window is hidden below an author of the site, and a row with per-document read grants is hidden from anyone without a grant (site admins of that site pass). Below an editor of the site, a hidden row answers 404 Content not found, indistinguishable from a wrong id.

Drafts are absent, not hidden

The filter runs in the query, so unpublished rows are absent from meta.total too, and so are rows you have no read grant for — against a site holding 80 drafts and 72 published rows of one type, the same request answers two different worlds:

the publication gate, observedbash
curl "$BASE/api/v1/content/docPage?siteId=docs&limit=3"
# "meta": { "total": 72,  "page": 1, "pageSize": 3, "totalPages": 24,  "hasMore": true }

curl -H "Authorization: Bearer $EDITOR_KEY" "$BASE/api/v1/content/docPage?siteId=docs&limit=1"
# "meta": { "total": 152, "page": 1, "pageSize": 1, "totalPages": 152, "hasMore": true }

Four ways to address a row

GET/api/v1/content/{type}?siteId={site}No auth

The paginated list, and the only read that filters, sorts and pages. Below an editor of the site it lists published rows only. Rows outside their display window are left out for every caller, unless an editor passes includeHidden=true.

200
{ "data": [ … ], "meta": { "total": 12, "page": 1, "pageSize": 10, "totalPages": 2, "hasMore": true } }
GET/api/v1/content/{type}/{id}?siteId={site}No auth

One row by id. The row must be of {type} and on the resolved site, or it is a 404. For an author or above of the site the response also carries a stats object and the row's editor association values (categories, tags, related content, expiration notify list); everyone else gets the row alone.

200
{ "data": { "id": "…", "title": "…", "isFeatured": false } }
GET/api/v1/content/slug/{slug}?siteId={site}No auth

By slug, across every content type — the type is not part of the address. It matches the stored slug exactly, which is the last path segment, not the path; to find a row by its path, use the list's path filter. Below an editor of the site only a published row is found, so a published row sharing the slug with a draft still answers.

200
{ "data": { "id": "…", "slug": "…", "path": "…" } }
GET/api/v1/content/by-id/{id}?siteId={site}No auth

Type-agnostic by id, for when you don't know the content type. /content/by-id/{id}/children returns its direct children in the list envelope, { data, meta }. The parent must be on the resolved site and visible to you, or it is a 404; children are filtered by the same three gates.

200
{ "data": { "id": "…", "contentTypeName": "article" } }

Structure is its own family: GET /nav for the navigation tree, /nav/{nodeId}/children and /nav/{nodeId}/breadcrumbs for a slice of it, and GET /tree for the raw content tree, which needs an author or above of the site. Pages under different parents can share a slug, and by-slug picks among them page-like content types first, then the oldest — nothing in the URL decides it. A Page and a Form may even share one as siblings. So prefer these routes over reconstructing hierarchy from slug or path strings.

Asking whether a row already exists

slug and path are exact-match filters on the list route, for answering "is there already something at /resources?" in one request. Paging a content type to find out risks a duplicate row at the same URL.

one request, one answerbash
curl "$BASE/api/v1/content/page?siteId=default&path=/ab-testing/"
# "data":  [ { "title": "A/B testing", "slug": "ab-testing", "path": "/ab-testing/" } ]
# "meta":  { "total": 1, "page": 1, "pageSize": 10, "totalPages": 1, "hasMore": false }

The stored path carries a leading and a trailing slash, so path=/ab-testing matches nothing. slug is the last segment alone — see Slugs, paths, and moving a page.

Query parameters on a content list

The query parameters a content list understands. Anything else is matched against the content type's declared field names — see the last row.
NameTypeDefaultDescription
siteIdstring—

Config slug or DB UUID. It selects the site; it is stripped before it can act as a filter. An id that names no site answers 404 SITE_NOT_FOUND.

page / limitnumber1 / 10

Clamped, not rejected: limit above 100 silently serves 100.

sort / dirstringcreatedAt / asc

dir is compared case-insensitively against desc; anything else, including a typo, sorts ascending. Sorting on a column your response would not include is a 400.

statusstring—

Honored for an editor of the site. Below that it is ignored, and published rows come back.

featured'true' | 'false'—

Narrows to rows that are, or are not, featured now. Any other value is a 400 VALIDATION_ERROR.

includeHidden'true'—

Keeps rows outside their display window. Honored for an editor of the site; ignored below that.

locale, parentId, searchstring—

search is a substring match on the title; parentId restricts to one node's children.

slug / pathstring—

Exact match on the two address columns.

(any declared field name)string—

Becomes an exact-match filter on that custom field. Filtering on a field you may not read is a 400. Any other name in the query string is discarded without comment.

Two things that can differ between callers

A query-string siteId selects the site and is then deleted from the filter set, so it cannot double as a filter that slips past the site check — see Site scoping and the siteId contract.

The row itself is shaped for the caller. Below an author of the site you get the public projection: internal columns such as internalNotes, createdBy, expiresAt, displayStart and displayStop are absent, and layout is cut down to what a visitor no audience matched is served. On top of that, field-level access runs on every custom field. So two callers reading the same row can legitimately get different keys, not just different rows: a missing field may mean your role, not an empty value. Sorting or filtering on such a field is refused with 400 Cannot filter or sort on: … rather than answered.