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:
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
/api/v1/content/{type}?siteId={site}No authThe 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.
{ "data": [ … ], "meta": { "total": 12, "page": 1, "pageSize": 10, "totalPages": 2, "hasMore": true } }/api/v1/content/{type}/{id}?siteId={site}No authOne 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.
{ "data": { "id": "…", "title": "…", "isFeatured": false } }/api/v1/content/slug/{slug}?siteId={site}No authBy 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.
{ "data": { "id": "…", "slug": "…", "path": "…" } }/api/v1/content/by-id/{id}?siteId={site}No authType-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.
{ "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.
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
| Name | Type | Default | Description |
|---|---|---|---|
siteId | string | — | 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 |
page / limit | number | 1 / 10 | Clamped, not rejected: |
sort / dir | string | createdAt / asc |
|
status | string | — | 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 |
includeHidden | 'true' | — | Keeps rows outside their display window. Honored for an editor of the site; ignored below that. |
locale, parentId, search | string | — |
|
slug / path | string | — | 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.