GraphQL API
The GraphQL API reads the same content as the Content API, as one typed schema per site. Use it when you want several models or nested references in one round trip, or a generated client from the schema. It is read-only: entries are written, published and deleted over the REST endpoints.
Every root field runs the REST read path, so a public key sees exactly what it sees over REST, filters accept the same operators, and the locale resolves the same way. If you know the Content API, the differences are only in spelling.
On a self-hosted instance the GraphQL API needs a license: on the Free plan every request, including the schema endpoint, answers 403 license_feature_graphql, and the console does not show the explorer. Plenary Cloud instances have it. See Licensing.
Every example on this page uses these placeholders:
| Placeholder | Meaning |
|---|---|
https://your-instance.plenarycms.io |
Your Plenary instance’s origin. The API lives under /api/v1. |
YOUR_API_KEY |
A public (pln_pub_…) or private (pln_prv_…) API key. See Authentication. |
post |
A collection model key. |
default, en-us |
A site key and a locale. |
Endpoints
Section titled “Endpoints”| Method and path | Purpose |
|---|---|
POST /api/v1/graphql |
Run an operation. The body is { "query": "…", "variables": { … }, "operationName": "…" }; only query is required. |
GET /api/v1/graphql?query=…&variables=…&operationName=… |
The same for tooling that wants a URL. Query operations only. |
GET /api/v1/graphql/schema |
The site’s schema as SDL, text/plain, for code generators. |
All three take site_key as a query parameter and resolve the site as every content read does: a key that belongs to a site reads that site when none is passed; a user token or an instance-wide private key must pass one; a public key passing another site’s key gets 403 permission_denied.
curl "https://your-instance.plenarycms.io/api/v1/graphql?site_key=default" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "{ post(limit: 3, sort: [PUBLISHED_AT_DESC]) { items { slug title data { summary } } } }" }'{ "data": { "post": { "items": [ { "slug": "hello-world", "title": "Hello, world", "data": { "summary": "…" } } ] } }}To generate types, save the SDL and point your generator at it:
curl "https://your-instance.plenarycms.io/api/v1/graphql/schema?site_key=default" \ -H "X-API-KEY: YOUR_API_KEY" > schema.graphqlFrom JavaScript, plenary.graphql in @plenary/client runs an operation and resolves with its data; from a shell, plenary graphql runs one and plenary graphql schema saves the SDL.
The console has an explorer too, under GraphQL in the Content group of the sidebar. Its editor completes and lints against the site’s schema, it runs as you or as one of the site’s public keys (so you can see the public projection a browser would get), and Copy SDL and Download SDL hand out the schema the editor completes against.
The schema
Section titled “The schema”A site’s schema is derived from its content models and rebuilt whenever a model changes. Every collection and singleton gets one root field named exactly like the model key — post, site_settings — and its types take the key in PascalCase: Post, PostData, PostWhere, PostSort, PostList. Forms and object models have no root field.
type Query { post(where: PostWhere, sort: [PostSort!], limit: Int = 100, offset: Int = 0, locale: String): PostList site_settings(locale: String): SiteSettings}
type PostList { items: [Post!]! total: Int}
type Post { id: ID! slug: String locale: String title: String status: String! site_key: String! model_key: String! path: String! folder_id: ID created_at: DateTime! updated_at: DateTime! published_at: DateTime publish_at: DateTime unpublish_at: DateTime data: PostData! draft: PostDraft}An entry has the same intrinsics as its REST shape, plus data with one field per model field. A collection’s root field answers a page (items) and, only when you select it, the total number of matching entries. A singleton’s root field answers the entry, or null when the locale has none. There is no separate by-id field: fetch one entry with a where on id or slug.
Introspection works, so GraphiQL and similar tools can explore the schema with your key. What they see is the same variant the key reads (see Public key restrictions).
Field types
Section titled “Field types”| Field type | GraphQL type | Notes |
|---|---|---|
| text, rich_text, email, url, phone, color, select, computed | String |
|
| number | Int when the field’s format is integer, else Float |
|
| boolean | Boolean |
|
| date, time, datetime | Date, Time, DateTime |
String scalars in the stored format (YYYY-MM-DD, HH:MM:SS, RFC 3339). |
| json, blocks | JSON |
Returned as stored. A Page Builder document carries variant_url on its images, as over REST. |
| image | Image |
media_id, alt, caption, focal_point { x y }, variants (a JSON map of variant name to URL), missing. |
| file | File |
media_id, alt, caption, missing. |
| multi_select, tags | [String!]! |
An unset field is []. |
| reference | The target model’s type, plus <field>_id: ID |
See References. |
| reference (multiple) | [Target!]!, plus <field>_ids: [ID!]! |
|
| user | User, plus <field>_id |
id, username, display_name, first_name, last_name, avatar_url, missing (true when no account has the id). |
| user (multiple) | [User!]!, plus <field>_ids |
|
| object | The object model’s type, e.g. Address |
Fields of the embedded object model. |
| list | [Item!]! |
A list of objects gets its own <Model><Field>Item type; a list of references or users reads as the multiple form above. |
An unset scalar is null; an unset list is [].
Filtering
Section titled “Filtering”The where argument takes a <Model>Where input: every filterable intrinsic (id, slug, locale, status, path, site_key, folder_id, created_at, updated_at, published_at), data with one filter per model field, and AND / OR lists of the same input. Conditions named beside AND or OR are combined with them.
Each filter input holds the Content API operators for its field type, spelled without the $:
| Input | Operators | Used by |
|---|---|---|
StringFilter |
eq ne lt lte gt gte in nin like ilike is_null |
Text-like fields, slug, locale, status, site_key |
NumberFilter, DateFilter, TimeFilter, DateTimeFilter |
eq ne lt lte gt gte in nin is_null |
Numbers, dates, times, instants, the _at intrinsics |
BooleanFilter, IDFilter, ReferenceFilter |
eq ne in nin is_null |
Booleans, id, folder_id, reference fields (by target id) |
PathFilter |
as StringFilter, plus under |
path — under: "/blog" matches the directory and everything below it |
NullFilter |
is_null |
Everything else: images, files, JSON, lists, objects, users |
{ post(where: { status: { eq: "published" } data: { views: { gt: 100 }, title: { ilike: "%graphql%" } } OR: [{ slug: { eq: "hello-world" } }, { data: { featured: { eq: true } } }] }) { items { slug } }}Private keys and user tokens can also filter on has_draft: true to find published entries with pending changes. A value the field cannot take — a malformed date, say — is refused with entry_query_invalid on that root field.
Sorting
Section titled “Sorting”sort is a list of <Model>Sort values applied left to right. Every intrinsic and every sortable data field (text-like, number, boolean, date, time, datetime) appears in both directions: CREATED_AT_DESC, SLUG_ASC, DATA_TITLE_ASC, DATA_VIEWS_DESC. Without sort, entries come newest first by created_at, as over REST.
Pagination
Section titled “Pagination”limit defaults to 100 and may not exceed 500; offset defaults to 0. Select total to get the number of entries matching where, counted with limit and offset ignored. The count runs only when you select it, so a plain read never pays for it.
query Page($offset: Int!) { post(sort: [PUBLISHED_AT_DESC], limit: 20, offset: $offset) { items { slug title } total }}Unlike the REST list endpoint, limit: 0 is refused rather than meaning unbounded.
Locale
Section titled “Locale”Each root field takes a locale argument. Without one, the request’s Accept-Language header decides, and without that the site’s default locale, exactly as a REST read. Two root fields in one operation can read different locales.
References
Section titled “References”A reference field selects the referenced entry with its own data, as deep as you nest. The stored id is always available beside it as <field>_id (or <field>_ids for a multiple reference), so a pointer survives whether or not you expand it.
{ post(where: { slug: { eq: "hello-world" } }) { items { title data { author_id author { slug data { name avatar { variants } } } related { slug data { author { data { name } } } } } } }}References resolve one level at a time with one fetch per level, so a query’s cost grows with its depth, not with the number of entries. At every level the referenced entry is checked as if you had read it directly: a target you may not read — a draft or a private model through a public key, a model outside your grants — is null for a single reference and left out of a multiple one, while its id stays. Multiple references resolve too, which the REST hydrate: parameter does not do.
Drafts
Section titled “Drafts”Through a private key or a user token, draft entries are listed and status is filterable; a published entry’s pending changes are under draft { slug data updated_at }, null when nothing is pending. A public key sees published entries as they are live. A public key with Include draft content turned on reads pending data and slug in place of the live ones and lists draft entries too, but never sees draft itself — the same rules as the Content API.
Operations, variables and fragments
Section titled “Operations, variables and fragments”Variables, fragments, inline fragments and aliases work as the GraphQL specification says. Use aliases to read one model twice with different arguments:
query Home($locale: String) { latest: post(limit: 5, sort: [PUBLISHED_AT_DESC], locale: $locale) { items { ...Card } } featured: post(where: { data: { featured: { eq: true } } }, locale: $locale) { items { ...Card } } site_settings(locale: $locale) { data { tagline } }}fragment Card on Post { slug title data { summary } }A document holding several operations must name the one to run in operationName.
Public key restrictions
Section titled “Public key restrictions”A public key gets the public variant of the schema. What a public key cannot read over REST is not in its schema at all, so it cannot be named: private models have no root field, private fields are absent from types, filters and sort values, and there is no draft field or has_draft filter. Selecting one of them fails validation with 400 graphql_query_invalid, the same as a typo. The SDL endpoint and introspection serve the same variant.
Within the schema a public key sees published entries on its own site, as they are live. A where on status, site_key or locale is combined with those rules and can only narrow the result.
A private key or user token gets the full schema, and each root field is then checked against the caller’s grants: a model you may not read on the site answers null with a permission_denied error on that field alone, while the other root fields are answered.
The key’s Allowed origins and Rate limit apply to every GraphQL request, including the SDL endpoint, before the operation runs. Each operation counts as one request against the rate limit, whatever it selects.
Limits
Section titled “Limits”An operation over any of these is refused with 400 before anything is read:
| Limit | Value | Code |
|---|---|---|
| Nesting depth (fragments included) | 10 | graphql_query_too_deep — vars.depth, vars.max |
| Root fields (aliases counted) | 20 | graphql_query_too_complex — vars.root_fields, vars.max_root_fields |
| Complexity | 10 000 nodes | graphql_query_too_complex — vars.complexity, vars.max |
| Query text | 50 KB | graphql_query_too_large — vars.bytes, vars.max |
| Execution time | 10 seconds | graphql_query_timeout |
Complexity estimates the size of the response. Every selected field costs one node per entry it is read on, so the fields you select under a collection’s items cost that collection’s limit each (the literal, the variable, or the default of 100). Nested references do not multiply the estimate, since the depth limit bounds them. Reading 500 entries with 21 fields each (10 502 nodes) is refused; the same with limit: 400, or 100 entries with any number of fields under 100, is fine.
Errors
Section titled “Errors”A response is { "data": …, "errors": [ … ] }. The status is 200 when the operation ran, even if a root field was refused: that field is null and its error is in errors, with the other fields answered. The status is 400 when the request did not parse, failed validation against the schema, or exceeded a limit; data is then null.
Every GraphQL error carries extensions.code with the same codes as the Content API, plus the code’s variables:
{ "data": { "post": null }, "errors": [ { "message": "entry_query_limit_exceeded", "path": ["post"], "extensions": { "code": "entry_query_limit_exceeded", "limit": 501, "max": 500 } } ]}A refusal of the request itself — no site, a malformed body, query text over the limit, a public key naming another site — uses the ordinary error envelope { "error": { "code": "…", "vars": { … } } } instead, as do authentication, origin and rate-limit refusals.
| Status | Code | Cause |
|---|---|---|
400 |
graphql_request_invalid |
The body is not a GraphQL request: malformed JSON, no query, a body over 1 MiB, or a non-query operation over GET. Error envelope. |
400 |
graphql_query_too_large |
Query text over 50 KB. Error envelope; vars.bytes, vars.max. |
400 |
graphql_query_invalid |
The query does not parse, or fails validation against the site’s schema: an unknown field, argument or type, or a private field or model named through a public key. |
400 |
graphql_query_too_deep |
Nesting deeper than 10. vars.depth, vars.max. |
400 |
graphql_query_too_complex |
More than 20 root fields, or a complexity over 10 000. |
422 |
model_site_key_required |
No site could be resolved. Error envelope. |
403 |
permission_denied |
Envelope: a public key named another site. On a root field: the caller may not read that model on the site. |
200 |
model_not_found |
On a root field: the model was deleted since the schema was built. |
200 |
entry_query_invalid |
On a root field: a where value the field cannot take. |
200 |
entry_query_limit_invalid, entry_query_limit_exceeded, entry_query_offset_invalid |
On a root field: limit below 1 or over 500 (vars.limit, vars.max), or a negative offset. |
200 |
entry_locale_invalid |
On a root field: locale is not a valid locale tag. |
200 |
graphql_query_timeout |
The operation did not finish within 10 seconds. |
200 |
graphql_execution_failed |
The executor refused the operation: a variable of the wrong type, or several operations without operationName. |
200 |
internal_server_error |
Unexpected server failure on a root field. Safe to retry. |
401 |
authentication_required, api_key_invalid, token_invalid |
As for every endpoint; see Authentication. |
403 |
api_key_origin_not_allowed |
The browser Origin is not in the key’s allowed origins. |
429 |
rate_limited |
The key’s per-minute limit is used up. |
403 |
license_feature_graphql |
Self-hosted on the Free plan: the GraphQL API is not included. Install a license. |
What stays on REST
Section titled “What stays on REST”Creating, updating, publishing and deleting entries, form definitions and submissions, media, revisions and everything administrative. Field selection by include and exclude has no equivalent because a GraphQL selection is one. Pagination is limit and offset, not cursors.
Related
Section titled “Related”- Content API: the REST reads this schema is built over, and the operator semantics.
- Field Types: what each field stores.
- Authentication: API keys and user tokens.
- Errors: codes from every endpoint.
@plenary/clientand the CLI: the JavaScript client method and the shell command.