# Reading content from outside

URL: https://kywi-docs-production.up.railway.app/integrating/reading-content-from-outside
Type: docPage

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](/agent/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 }

## the publication gate, observed

## Four ways to address a row

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`.

{ "data": [ … ], "meta": { "total": 12, "page": 1, "pageSize": 10, "totalPages": 2, "hasMore": true } }

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.

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.

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.

## By-slug and by-id were ungated before 0.25.0

On earlier versions `GET /content/slug/{slug}` and `GET /content/by-id/{id}` (with its `/children`) run no publication-status check, and neither by-id route reads a credential at all: a caller with no credential gets drafts. On those versions, put your own status filter in front of them, or route a non-editor audience through the typed list and typed by-id reads.

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.

## URL Override is the public address

A page with a URL Override is served at the override. `GET /nav` gives it as the item’s `href`; `/nav/{nodeId}/children` returns `urlOverride` beside `path`, which stays the tree path. Content and search responses carry `urlOverride` too, and a search hit’s `path` is already the public address. `?path=` on the content list matches either.

## Nav Visibility by Group

For a call made with a person’s session token, the nav routes leave out items hidden from any of that person’s groups, with everything beneath, and the children route answers 404 for a node that is hidden from them or sits under one that is. When the site hides any item from a group, that answer is sent `Cache-Control: private, no-store`. An API key or an OAuth client token gets the tree unfiltered by group, cacheable, whatever groups its owner belongs to — so a headless front end that wants per-group navigation has to call with the visitor’s own session, or filter on its side. Breadcrumbs and named menus are never filtered by group.

## 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 }

## one request, one answer

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](/authoring/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.

## 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](/integrating/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.
