GraphQL: the read-only subset
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.
/api/v1/graphqlNo authBody 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.
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.
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. 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.
{
"errors": [
{ "message": "Content type \"invoice\" is not available via GraphQL" }
]
}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.