Skip to content

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

Terminal window
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:

Terminal window
curl "https://your-instance.plenarycms.io/api/v1/graphql/schema?site_key=default" \
-H "X-API-KEY: YOUR_API_KEY" > schema.graphql

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

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 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 [].

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.