GraphQL
Colophon has a read-only GraphQL endpoint for tools that would rather speak GraphQL than JSON over REST. It
reads drafts, with the same query engine and the same permission checks as the management API’s
POST …/entries/query: a GraphQL query and its REST twin run the same document and get the same answer.
Your website should keep reading published content from the delivery API.
POST /api/v1/projects/{project}/environments/{environment}/collections/{collection}/graphqlThere is one endpoint per content type: {collection} is its address name, and the schema is that content
type’s. It takes the same credentials as the management API: an API token or a person’s
sign-in, in Authorization: Bearer …. A token needs content.read on the content type. The examples use the
recipes content type from the quick start (fields dish, minutes and method).
A first query
Section titled “A first query”The body is the usual GraphQL-over-HTTP request, sent as application/json:
| Member | Required | What it is |
|---|---|---|
query |
Yes | The GraphQL document, at most 8,192 characters |
operationName |
No | Which operation to run, when the document names several |
variables |
No | An object of variable values |
Any other member is refused with 400 malformed_json, and a body without Content-Type: application/json
with 415 unsupported_media_type.
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/graphql" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"query": "{ entries(first: 5) { nodes { id title dish minutes published { generation } } pageInfo { endCursor hasNextPage } applied { query queryHash } } }"}'Response: 200 OK, the one recipe there is
HTTP/1.1 200 OKcontent-type: application/jsonx-request-id: 01a1ee84-376c-74dc-ab16-f0a138e53f0econtent-length: 392date: Wed, 18 Nov 2026 11:56:44 GMT
{ "data": { "entries": { "nodes": [ { "id": "01a1ee81-13ee-70ff-9989-321e046286f8", "title": "Lemon tart", "dish": "Lemon tart", "minutes": 45.0, "published": { "generation": 1 } } ], "pageInfo": { "endCursor": null, "hasNextPage": false }, "applied": { "query": { "depth": 0, "fields": [ "dish", "minutes" ], "filters": [], "limit": 5, "sort": [] }, "queryHash": "sha256:5a656ae54c6bf886480878c954ab51fba90a34f48c7023e08461aa3901a305d2" } } }}The answer is GraphQL’s own {"data": …, "errors": […]}, not the {"data": …} wrapper the REST routes use.
The schema
Section titled “The schema”The schema is built for each request from the project’s content types and the caller’s role. It has two reads at the root, and nothing else:
type Query { entries(where: recipesFilter, orderBy: [recipesSort!], first: Int, after: String): recipesConnection entry(id: ID!): recipes}
type recipesConnection { nodes: [recipes!]! pageInfo: PageInfo! applied: AppliedQuery!}
type PageInfo { endCursor: String, hasNextPage: Boolean! }type AppliedQuery { query: JSON!, queryHash: String! }entriesanswers a page of drafts.firstis the page size, 1 to 100 (20 when you leave it out);aftertakes the previous page’spageInfo.endCursor.whereandorderByexist only when the content type has a filterable field (below).entry(id:)reads one draft. It isnullwhen there is no such entry, when your role can’t read it, and when the id isn’t a UUID: the three look the same.appliedis the query that ran, as the canonical JSON documentPOST …/entries/querytakes, and its hash. The same document sent to the REST route answers the samequery_hash.
Node fields
Section titled “Node fields”Each content type is an object type named after its address name (recipes). A hyphen or any other
character GraphQL doesn’t allow becomes _, a name starting with a digit gains a leading _, and a name
GraphQL keeps for itself (Query, type, input and so on) gains Entry. Every node has these fields, which
are the management API’s draft fields in camelCase:
| Field | Type | What it is |
|---|---|---|
id |
ID! |
The entry’s id |
collection |
String! |
Its content type’s address name |
revisionId |
ID |
The current draft revision |
title |
String |
The draft’s title; empty when your role can’t read the field it comes from |
hiddenFields |
[String!] |
Fields your role can’t read, left out of the answer; [] when you read them all |
published |
Publication |
{ revisionId generation } of the live revision, or null if the entry isn’t published |
locale |
String |
Its language tag, or null |
createdAt, updatedAt |
String |
RFC 3339 times |
createdBy |
ID! |
Who made the entry |
content |
JSON |
Every field you may read, as one JSON object |
Then each content field is a field of its own, typed by its kind:
| Field kind | GraphQL type |
|---|---|
| Number | Float (so 45 comes back as 45.0) |
| Yes or no | Boolean |
| Rich text, JSON, group, list, blocks | JSON: the stored value as it is |
| Many uploads, many linked entries | [String!]: their ids |
| One linked entry | The target content type’s object type, or ID if your role can’t read the target |
| Everything else (text, choice, dates and times, email, web address, URL name, colour, one upload) | String |
A content field whose id is one of the node field names above (a field called title, say) keeps working
under the name field_title, so neither hides the other.
Here is the Lemon tart by id, with every node field and its content:
curl "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/graphql" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"query": "{ entry(id: \"01a1ee81-13ee-70ff-9989-321e046286f8\") { id title dish minutes method published { revisionId generation } createdAt updatedAt createdBy hiddenFields locale revisionId collection } }"}'Response: one draft
{ "data": { "entry": { "id": "01a1ee81-13ee-70ff-9989-321e046286f8", "title": "Lemon tart", "dish": "Lemon tart", "minutes": 45.0, "method": { "doc": { "content": [ { "content": [ { "text": "Blind-bake the pastry, then fill it with lemon curd and bake until just set.", "type": "text" } ], "type": "paragraph" } ], "type": "doc" }, "schema": "colophon/rich-text", "version": 1 }, "published": { "revisionId": "01a1ee81-143c-7776-99d8-ece782907784", "generation": 1 }, "createdAt": "2026-11-18T11:53:19.083162Z", "updatedAt": "2026-11-18T11:53:19.160733Z", "createdBy": "01a1ee81-12ca-7536-9917-c29fb332ce0e", "hiddenFields": [], "locale": null, "revisionId": "01a1ee81-143c-7776-99d8-ece782907784", "collection": "recipes" } }}The content fields you select become the document’s fields, so the server reads only those. content
holds the same narrowed set: on its own it returns every field your role may read (numbers as stored, 45),
but next to dish it holds only {"dish": …}.
Filter and sort
Section titled “Filter and sort”where and orderBy can only name filterable fields: those marked "index": true in the content type,
as the delivery API’s Filter and sort explains. The arguments are built from
those fields, so on a content type with none, entries has no where or orderBy at all. In the quick
start’s recipes, nothing is filterable yet:
curl "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/graphql" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"query": "{ entries(where: {minutes: {lte: 30}}) { nodes { dish } } }"}'{"data":null,"errors":[{"message":"Unknown argument \"where\" on field \"entries\" of type \"Query\".","locations":[{"line":1,"column":11}]}]}Mark minutes filterable with the PUT …/content-types/recipes shown on the Delivery
API page. The schema then gains these inputs:
input recipesFilter { minutes: recipesFilter_minutes }input recipesFilter_minutes { eq: Float, in: [Float!], lt: Float, lte: Float, gt: Float, gte: Float }input recipesSort { field: recipesOrderable!, dir: SortDirection = ASC }enum recipesOrderable { minutes }enum SortDirection { ASC DESC }Each operator inside where is one filter, and every filter must match. The operators a field offers follow
its kind, as in the query document: eq and in on every filterable field; lt, lte, gt, gte also on
text, numbers, dates, times and URL names; contains on single-line text. The query document’s own limits
still apply: at most 8 filters, 4 sort keys and 100 values in an in. The entry id breaks ties in the sort,
so paging is stable.
With two more draft recipes saved (Ginger biscuits, 18 minutes; Flapjacks, 25), ask for those that take 30 minutes or less, quickest first, one to a page. Variables work as in any GraphQL server:
curl "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/graphql" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "query Quick($most: Float) { entries(where: {minutes: {lte: $most}}, orderBy: [{field: minutes, dir: ASC}], first: 1) { nodes { id title minutes published { generation } } pageInfo { endCursor hasNextPage } applied { query queryHash } } }", "operationName": "Quick", "variables": { "most": 30 } }'Response: the first page, and a cursor for the next
{ "data": { "entries": { "nodes": [ { "id": "01a1ee84-8d1c-760a-82a7-f39ca86a9e1b", "title": "Ginger biscuits", "minutes": 18.0, "published": null } ], "pageInfo": { "endCursor": "djE6NmY4YzZjOWQzYzhkODI4ZGMxYWQ2NmY5MTkwNjcyYWQyYzJhM2M1NzY4MmVlMTUzYmY0MTAwNWQwZGM3NGRiNjpbMTgsIjAxYTFlZTg0LThkMWMtNzYwYS04MmE3LWYzOWNhODZhOWUxYiJd", "hasNextPage": true }, "applied": { "query": { "depth": 0, "fields": [ "minutes" ], "filters": [ { "field": "minutes", "op": "lte", "value": 30 } ], "limit": 1, "sort": [ { "dir": "asc", "field": "minutes" } ] }, "queryHash": "sha256:6f8c6c9d3c8d828dc1ad66f9190672ad2c2a3c57682ee153bf41005d0dc74db6" } } }}published is null: Ginger biscuits is a draft that was never published, which the delivery API would never
show. applied.query is the document POST …/entries/query takes; sending it there returns the same
query_hash, sha256:6f8c6c9d….
The next page. Pass endCursor back as after, with the same where, orderBy and first:
curl "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/graphql" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": "query Quick($most: Float, $after: String) { entries(where: {minutes: {lte: $most}}, orderBy: [{field: minutes, dir: ASC}], first: 1, after: $after) { nodes { title minutes } pageInfo { endCursor hasNextPage } } }", "variables": { "most": 30, "after": "djE6NmY4YzZjOWQzYzhkODI4ZGMxYWQ2NmY5MTkwNjcyYWQyYzJhM2M1NzY4MmVlMTUzYmY0MTAwNWQwZGM3NGRiNjpbMTgsIjAxYTFlZTg0LThkMWMtNzYwYS04MmE3LWYzOWNhODZhOWUxYiJd" } }'{"data":{"entries":{"nodes":[{"title":"Flapjacks","minutes":25.0}],"pageInfo":{"endCursor":null,"hasNextPage":false}}}}A cursor belongs to the query that made it. With a different query it is refused with foreign_cursor
(errors below).
A filter or sort on a field your role can’t read is refused with field_not_readable, so a query can’t learn
a hidden field’s values by sorting on it.
Linked entries
Section titled “Linked entries”A field that links to one entry (a single reference) resolves to the target’s own object type, so you can
select its fields in place. Selecting only id or collection costs nothing: those are stored in the link
itself. Selecting anything more reads the linked entry, which costs one level of the document’s depth, and
a link inside that link costs another. For a content type with an author field linking to staff, whose
own mentor field links to staff again:
{ entries { nodes { title author { # depth 1: reads the linked staff entry name mentor { id } # still depth 1: the id is in the link } } }}Two levels are the most: author { mentor { name } } is depth 2, and a third level is refused with
out_of_range at /depth. A linked entry your role can’t read at all is typed ID and answers just its id.
Fields that link to many entries answer a list of ids; read those entries with entry(id:) or a second
query.
Bounds
Section titled “Bounds”The first five bounds are checked on the document’s text before anything is read, and answered in the error
envelope with 422 validation_failed; the last two are checked as the query runs and come back
as GraphQL errors.
| Bound | Limit | reason / extensions.code |
|---|---|---|
Length of query |
8,192 characters | too_large (envelope) |
| Nesting of selections, with every fragment expanded | 16 levels | too_deep (envelope) |
Brackets { [ ( nested in the raw text |
64 levels | too_deep (envelope) |
| Fields selected, with every fragment expanded | 512 | too_complex (envelope) |
| Fragments that spread one another in a cycle | none allowed | fragment_cycle (envelope) |
entries and entry calls in one request, aliases counted |
8 | too_many (GraphQL error) |
Fields selected inside one nodes or entry, aliases counted |
128 | too_many (GraphQL error) |
A full introspection query fits comfortably inside these. Here is a document that selects 600 fields:
HTTP/1.1 422 Unprocessable Entitycontent-type: application/jsonx-request-id: 01a1ee84-e7aa-720c-955b-3347a3081ae3content-length: 214date: Wed, 18 Nov 2026 11:57:29 GMT
{ "error": { "code": "validation_failed", "message": "a document selects at most 512 fields, fragments expanded", "details": { "reason": "too_complex", "pointer": "/query" }, "request_id": "01a1ee84-e7aa-720c-955b-3347a3081ae3" }}And one with nine aliased entries calls (r0: entries(first: 1) { … } r1: …). The first eight run; the
ninth is refused:
{ "data": { "r0": { "nodes": [{ "id": "01a1ee81-13ee-70ff-9989-321e046286f8" }] }, "r1": { "nodes": [{ "id": "01a1ee81-13ee-70ff-9989-321e046286f8" }] }, "r2": { "nodes": [{ "id": "01a1ee81-13ee-70ff-9989-321e046286f8" }] }, "r3": { "nodes": [{ "id": "01a1ee81-13ee-70ff-9989-321e046286f8" }] }, "r4": { "nodes": [{ "id": "01a1ee81-13ee-70ff-9989-321e046286f8" }] }, "r5": { "nodes": [{ "id": "01a1ee81-13ee-70ff-9989-321e046286f8" }] }, "r6": { "nodes": [{ "id": "01a1ee81-13ee-70ff-9989-321e046286f8" }] }, "r7": { "nodes": [{ "id": "01a1ee81-13ee-70ff-9989-321e046286f8" }] } }, "errors": [ { "message": "a request runs at most 8 root reads", "locations": [{ "line": 1, "column": 315 }], "extensions": { "code": "too_many", "pointer": "" } } ]}Errors
Section titled “Errors”A GraphQL request can fail in two places, and the answer looks different in each.
Before the document runs, the route answers like every other route: an HTTP error status and the
error envelope. That covers a missing or bad credential (401), a role that can’t read the
content type (403 missing_permission), a content type that doesn’t exist (404 not_found), a body that
isn’t the GraphQL request (400 malformed_json, 415 unsupported_media_type), variables that isn’t an
object (422 with wrong_type), the bounds checked on the document, and rate limits
(429).
Once the document runs, the status is 200 OK and problems are GraphQL errors in errors. Syntax and
schema errors (an unknown field or argument) carry only message and locations. A refusal from Colophon
also carries extensions.code and extensions.pointer: the same details.reason and details.pointer the
REST route would answer, so a client can branch on the same values. Asking for more than 100 at a time:
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/graphql" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"query": "{ entries(first: 500) { nodes { title } } }"}'HTTP/1.1 200 OKcontent-type: application/jsonx-request-id: 01a1ee85-64b3-741d-b2cb-a6a313705c39content-length: 170date: Wed, 18 Nov 2026 11:58:01 GMT
{ "data": null, "errors": [ { "message": "`limit` is a whole number from 1 to 100", "locations": [{ "line": 1, "column": 3 }], "extensions": { "code": "out_of_range", "pointer": "/limit" } } ]}first became the document’s limit, so the pointer names /limit. A cursor from another query:
{"data":null,"errors":[{"message":"this cursor is not valid for this query","locations":[{"line":1,"column":3}],"extensions":{"code":"foreign_cursor","pointer":""}}]}Always check errors, even on a 200.
What it doesn’t do
Section titled “What it doesn’t do”- No writes. There are no mutations and no subscriptions; a
mutationis answered “Schema is not configured for mutations.” Write through the management API. - No published content. GraphQL reads drafts. Published content, pinned releases and the cache headers a CDN needs are on the delivery API, which is REST only.
- One content type per endpoint.
entriesandentryread the content type in the path. Linked entries can be read through their links, up to two levels.
Introspection
Section titled “Introspection”Introspection is on, so GraphQL tools (GraphiQL, code generators, editor plugins) can be pointed at the
endpoint with the Authorization header. The schema shows exactly what the caller may read: the content type
in the path and the content types its links reach. The schema is rebuilt on every request, so a field made
filterable appears in where and orderBy at once.
curl "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/graphql" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"query": "{ __type(name: \"Query\") { fields { name args { name } } } }"}'