# GraphQL: the read-only subset

URL: https://kywi-docs-production.up.railway.app/integrating/graphql-the-read-only-subset
Type: docPage

One `POST /graphql` route exposes seven read-only Query fields over types that opted in with `graphql: true`; a query that errors comes back as HTTP 400.

The schema is built with a query type and nothing else — there is no Mutation, no subscription, and no GET or GraphiQL surface. Everything you can do through GraphQL you can also do through REST; what GraphQL buys is picking the fields, over one round trip.

Body is `{ "query": "…", "variables": { … } }`. The `Authorization` header is optional: without one the request runs as an anonymous caller rather than being rejected.

## The seven fields

type Query { content(id: String!): Content contentBySlug(slug: String!, siteId: String): Content contentList(contentType: String!, siteId: String, limit: Int, page: Int, status: String): [Content] search(query: String!, siteId: String, contentType: String, limit: Int): [SearchResult] categories(siteId: String): [Category] nav(siteId: String): [NavNode] media(id: String!): Media }

`Content` carries the row's own columns — title, slug, status, baseType, contentTypeName, body, summary, locale, path, urlOverride and the three timestamps — plus a computed `isFeatured: Boolean!`, true when Feature in Section is Yes, or Scheduled and now inside Feature Start/End. There is no `layout` field, so a page's layout document is not reachable here; that is a REST read. `SearchResult` is narrower than its REST counterpart: six fields (id, title, slug, path, urlOverride, contentTypeName), with no `summary` and no `publishedAt`. Its `path` is the page's public address, the URL Override when one is set, so a hit is linkable as it stands.

## siteId is optional

Leave `siteId` out and the site is the one the request's Host header resolves to, else the first configured site. Pass it as the config slug or the DB UUID; an id that names no site is an error with `extensions.code: "SITE_NOT_FOUND"`, not a fallback. Before 0.25.0 every `siteId` argument is non-null, so a query that leaves it out is rejected before any resolver runs. What `siteId` means across the rest of the API is [Site scoping and the `siteId` contract](/integrating/site-scoping-and-the-siteid-contract/).

## Who sees which rows

A published row inside its display window is public. Anything else is hidden below a threshold set on *the row's own* site: a draft (any status but published) needs an editor or above of that site, a row outside its display window needs an author or above, and a row with per-document read grants needs a grant, or a site admin of that site. A hidden row is `null` from `content` and `contentBySlug` and simply absent from `contentList`, `search` and `nav`. `contentList` leaves out rows outside their display window for every caller.

`content(id)` and `media(id)` take no site argument because they check the row after fetching it. Media has no public tier at all: it needs access to the row's site, so an anonymous caller asking for a media id gets `null`, not an error.

## Drafts need an editor of the site

Before 0.25.0 any member of the site, readers and read-scope keys included, could read its drafts through GraphQL, and only `contentList` checked the display window; read grants were not checked.

## Opting a content type in

Nothing is queryable until its content type sets `graphql: true`. A missing flag and `graphql: false` are the same answer. Naming a non-opted type is loud: `contentList`, or `search` with that `contentType`, throws. Everything else is quiet: `content` and `contentBySlug` return `null` for a row of a non-opted type, and `search` with no `contentType` drops non-opted hits instead of failing. Introspection is told the answer too: the `contentType` argument's description lists the opted-in names, so a client can discover the set instead of probing for it.

## Errors are HTTP 400

Any query that produces errors comes back as 400 with graphql-js's own `{ "errors": [ … ] }` body — not the `{ "error": { "code", "message" } }` [envelope the REST routes use](/integrating/the-response-envelope-pagination-and-errors/). Unparseable JSON and a missing `query` are 400 as well. So a client that branches on `response.ok` will treat a field-level error the same as a transport failure; read the body either way. A request the API refuses before GraphQL runs answers in the REST envelope instead, such as 403 `PASSWORD_RESET_REQUIRED` for a session whose user must set a new password.

## Rate limits and unknown site ids are refused before GraphQL

Two more refusals come back in the REST envelope: 429 `RATE_LIMITED` for an API key or OAuth client token over its rate limit, and 404 `SITE_NOT_FOUND` for a `?siteId=` query parameter that names no site.

## POST /api/v1/graphql — 400

The other denial you will meet is `{"message": "Unauthorized"}`, thrown when a caller below editor of the site asks `contentList` for a status other than published. Asking for nothing is treated more kindly: an absent status silently narrows to published rather than failing. `nav` applies Nav Visibility by Group as well, for a signed-in user’s session but not for an API key or OAuth client token.
