GraphQL API
Craft Pro provides an autogenerated GraphQL (opens new window) API for your content, which you can query to pull your content into separate applications, such as single-page apps (SPAs) or static site generators.
# Examples
# Query
{
entries (section: "news", limit: 2, orderBy: "dateCreated DESC") {
dateCreated @formatDateTime (format: "Y-m-d")
title
children {
title
}
... on news_article_Entry {
shortDescription
featuredImage {
url @transform (width: 300, immediately: true)
}
}
}
}
# Mutation
mutation saveEntry($title: String, $slug: String) {
save_news_article_Entry(title: $title, slug: $slug) {
title
slug
dateCreated @formatDateTime (format: "Y-m-d")
}
}
# query variables:
{
"title": "Craft 3.5 Supports GraphQL Mutations",
"slug": "craft-graphql-mutations"
}
# Getting Started
Before you begin, make sure that you’re running Craft Pro 3.3 or later and the enableGql
setting has not been set to false
.
# Create Your API Endpoint
The first step to adding a GraphQL API to your project is to set up a public endpoint for it.
To do that, create a URL rule from config/routes.php
that points to the graphql/api
controller action. For example, the following URL rule would cause /api
requests to route to the GraphQL API:
return [
'api' => 'graphql/api',
// ...
];
You can verify that your endpoint is configured correctly, try sending a {ping}
query to it.
curl -H "Content-Type: application/graphql" -d '{ping}' http://my-project.test/api
(Replace http://my-project.test/api
with the actual URL to your endpoint.)
If that comes back with the following JSON response, then your GraphQL API is up and running!
{"data":{"ping":"pong"}}
You may also want to limit allowed GraphQL origins using the allowedGraphqlOrigins
setting, as Craft sets an access-control-allow-origin: *
header by default on GraphQL responses.
# Define Your Schemas
Once you’ve created a GraphQL API endpoint, you need to tell Craft which content should be available from it. (No content is available by default.) You do that by defining a Schema.
Craft has two types of schemas:
- The Public Schema defines which content should be available publicly.
- You can also define multiple private schemas, which each have their own secret Access Token.
You can manage your schemas from the control panel, at GraphQL → Schemas. In addition to defining the scope of each schema, you can also give them expiration dates, or disable them.
When performing a GraphQL API request, the schema will be determined automatically based on the token that is supplied (if any). See below to learn how to do that.
# Sending API Requests
# Using the GraphiQL IDE
The easiest way to start exploring your GraphQL API is with the built-in GraphiQL (opens new window) IDE, which is available in the control panel from GraphQL → Explore.
# Using Another IDE
Additional GraphQL IDEs are available as well:
- Insomnia (opens new window)
- GraphQL Playground (opens new window)
- GraphQL Playground online (opens new window)
When you are initially exploring the API, make sure that Dev Mode is enabled so the IDE can be informed about the entire schema available to it.
# Sending Requests Manually
The GraphQL API can be queried in three ways:
- Using a
GET
request, with the GraphQL query defined by aquery
parameter:curl \ --data-urlencode "query={ping}" \ http://craft32.test/api # or curl http://craft32.test/api?query=%7Bping%7D
- Using a
POST
request with anapplication/json
content type, with the GraphQL query defined by aquery
key:curl \ -H "Content-Type: application/json" \ -d '{"query":"{ping}"}' \ http://my-project.test/api
- Using a
POST
request with anapplication/graphql
content type, with the GraphQL query defined by the raw request body:curl \ -H "Content-Type: application/graphql" \ -d '{ping}' \ http://my-project.test/api
# Specifying Variables
If you need to specify any variables (opens new window) along with your query, then you must send request as a POST
request with an application/json
content type, and include a variables
key in the JSON body alongside query
.
curl \
-H "Content-Type: application/json" \
-d '{
"query": "query($id:[Int]) { entries(id: $id) { id, title } }",
"variables": { "id": [1, 2, 3] }
}' \
http://my-project.test/api
# Querying a Private Schema
The Public Schema will be used by default. To query against a different schema, pass its Access Token using an Authorization
header.
curl \
-H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/graphql" \
-d '{entries{id}}' \
http://my-project.test/api
If you’re unable to query a private schema because of a “missing authorization header”, make sure Craft received it from the web server with a quick post to a test template:
{{ craft.app.getRequest().getHeaders().has('authorization') ?
'auth token present ✓' :
'auth token missing!' }}
Apache strips Authorization
headers by default, which can be fixed by enabling CGIPassAuth (opens new window) or adding the following to your .htaccess
file:
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
# Caching
All query results are cached, so that repeated queries can yield results faster. The GraphQL result cache does not have a sophisticated ruleset on invalidating the cache - if the site's content or structure changes, the entire cache is invalidated.
Craft has GraphQL result caching enabled by default, but it can be disabled with the enableGraphQlCaching (opens new window) config setting.
# Interface Implementation
A defined type exists for each specific interface implementation. For example, if a “News” section has “Article” and “Editorial” entry types, in addition to the EntryInterface
interface type, two additional types would be defined the GraphQL schema, if the token used allows it: news_article_Entry
and news_editorial_Entry
types.
# Query Reference
The actual API features will depend on what your schema allows.
# The assets
query
This query is used to query for assets.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
volumeId | [QueryArgument] | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. |
volume | [String] | Narrows the query results based on the volumes the assets belong to, per the volumes’ handles. |
folderId | [QueryArgument] | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. |
filename | [String] | Narrows the query results based on the assets’ filenames. |
kind | [String] | Narrows the query results based on the assets’ file kinds. |
height | [String] | Narrows the query results based on the assets’ image heights. |
width | [String] | Narrows the query results based on the assets’ image widths. |
size | [String] | Narrows the query results based on the assets’ file sizes (in bytes). |
dateModified | String | Narrows the query results based on the assets’ files’ last-modified dates. |
includeSubfolders | Boolean | Broadens the query results to include assets from any of the subfolders of the folder specified by folderId . |
withTransforms | [String] | A list of transform handles to preload. |
uploader | QueryArgument | Narrows the query results based on the user the assets were uploaded by, per the user’s ID. |
# The assetCount
query
This query is used to return the number of assets.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
volumeId | [QueryArgument] | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. |
volume | [String] | Narrows the query results based on the volumes the assets belong to, per the volumes’ handles. |
folderId | [QueryArgument] | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. |
filename | [String] | Narrows the query results based on the assets’ filenames. |
kind | [String] | Narrows the query results based on the assets’ file kinds. |
height | [String] | Narrows the query results based on the assets’ image heights. |
width | [String] | Narrows the query results based on the assets’ image widths. |
size | [String] | Narrows the query results based on the assets’ file sizes (in bytes). |
dateModified | String | Narrows the query results based on the assets’ files’ last-modified dates. |
includeSubfolders | Boolean | Broadens the query results to include assets from any of the subfolders of the folder specified by folderId . |
withTransforms | [String] | A list of transform handles to preload. |
uploader | QueryArgument | Narrows the query results based on the user the assets were uploaded by, per the user’s ID. |
# The asset
query
This query is used to query for a single asset.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
volumeId | [QueryArgument] | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. |
volume | [String] | Narrows the query results based on the volumes the assets belong to, per the volumes’ handles. |
folderId | [QueryArgument] | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. |
filename | [String] | Narrows the query results based on the assets’ filenames. |
kind | [String] | Narrows the query results based on the assets’ file kinds. |
height | [String] | Narrows the query results based on the assets’ image heights. |
width | [String] | Narrows the query results based on the assets’ image widths. |
size | [String] | Narrows the query results based on the assets’ file sizes (in bytes). |
dateModified | String | Narrows the query results based on the assets’ files’ last-modified dates. |
includeSubfolders | Boolean | Broadens the query results to include assets from any of the subfolders of the folder specified by folderId . |
withTransforms | [String] | A list of transform handles to preload. |
uploader | QueryArgument | Narrows the query results based on the user the assets were uploaded by, per the user’s ID. |
# The entries
query
This query is used to query for entries.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
withStructure | Boolean | Explicitly determines whether the query should join in the structure data. |
structureId | Int | Determines which structure data should be joined into the query. |
level | Int | Narrows the query results based on the elements’ level within the structure. |
hasDescendants | Boolean | Narrows the query results based on whether the elements have any descendants. |
ancestorOf | Int | Narrows the query results to only elements that are ancestors of another element. |
ancestorDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by ancestorOf . |
descendantOf | Int | Narrows the query results to only elements that are descendants of another element. |
descendantDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by descendantOf . |
leaves | Boolean | Narrows the query results based on whether the elements are “leaves” (element with no descendants). |
nextSiblingOf | Int | Narrows the query results to only the entry that comes immediately after another element. |
prevSiblingOf | Int | Narrows the query results to only the entry that comes immediately before another element. |
positionedAfter | Int | Narrows the query results to only entries that are positioned after another element. |
positionedBefore | Int | Narrows the query results to only entries that are positioned before another element. |
editable | Boolean | Whether to only return entries that the user has permission to edit. |
section | [String] | Narrows the query results based on the section handles the entries belong to. |
sectionId | [QueryArgument] | Narrows the query results based on the sections the entries belong to, per the sections’ IDs. |
type | [String] | Narrows the query results based on the entries’ entry type handles. |
typeId | [QueryArgument] | Narrows the query results based on the entries’ entry types, per the types’ IDs. |
authorId | [QueryArgument] | Narrows the query results based on the entries’ authors. |
authorGroup | [String] | Narrows the query results based on the user group the entries’ authors belong to. |
authorGroupId | [QueryArgument] | Narrows the query results based on the user group the entries’ authors belong to, per the groups’ IDs. |
postDate | [String] | Narrows the query results based on the entries’ post dates. |
before | String | Narrows the query results to only entries that were posted before a certain date. |
after | String | Narrows the query results to only entries that were posted on or after a certain date. |
expiryDate | [String] | Narrows the query results based on the entries’ expiry dates. |
# The entryCount
query
This query is used to return the number of entries.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
withStructure | Boolean | Explicitly determines whether the query should join in the structure data. |
structureId | Int | Determines which structure data should be joined into the query. |
level | Int | Narrows the query results based on the elements’ level within the structure. |
hasDescendants | Boolean | Narrows the query results based on whether the elements have any descendants. |
ancestorOf | Int | Narrows the query results to only elements that are ancestors of another element. |
ancestorDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by ancestorOf . |
descendantOf | Int | Narrows the query results to only elements that are descendants of another element. |
descendantDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by descendantOf . |
leaves | Boolean | Narrows the query results based on whether the elements are “leaves” (element with no descendants). |
nextSiblingOf | Int | Narrows the query results to only the entry that comes immediately after another element. |
prevSiblingOf | Int | Narrows the query results to only the entry that comes immediately before another element. |
positionedAfter | Int | Narrows the query results to only entries that are positioned after another element. |
positionedBefore | Int | Narrows the query results to only entries that are positioned before another element. |
editable | Boolean | Whether to only return entries that the user has permission to edit. |
section | [String] | Narrows the query results based on the section handles the entries belong to. |
sectionId | [QueryArgument] | Narrows the query results based on the sections the entries belong to, per the sections’ IDs. |
type | [String] | Narrows the query results based on the entries’ entry type handles. |
typeId | [QueryArgument] | Narrows the query results based on the entries’ entry types, per the types’ IDs. |
authorId | [QueryArgument] | Narrows the query results based on the entries’ authors. |
authorGroup | [String] | Narrows the query results based on the user group the entries’ authors belong to. |
authorGroupId | [QueryArgument] | Narrows the query results based on the user group the entries’ authors belong to, per the groups’ IDs. |
postDate | [String] | Narrows the query results based on the entries’ post dates. |
before | String | Narrows the query results to only entries that were posted before a certain date. |
after | String | Narrows the query results to only entries that were posted on or after a certain date. |
expiryDate | [String] | Narrows the query results based on the entries’ expiry dates. |
# The entry
query
This query is used to query for a single entry.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
withStructure | Boolean | Explicitly determines whether the query should join in the structure data. |
structureId | Int | Determines which structure data should be joined into the query. |
level | Int | Narrows the query results based on the elements’ level within the structure. |
hasDescendants | Boolean | Narrows the query results based on whether the elements have any descendants. |
ancestorOf | Int | Narrows the query results to only elements that are ancestors of another element. |
ancestorDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by ancestorOf . |
descendantOf | Int | Narrows the query results to only elements that are descendants of another element. |
descendantDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by descendantOf . |
leaves | Boolean | Narrows the query results based on whether the elements are “leaves” (element with no descendants). |
nextSiblingOf | Int | Narrows the query results to only the entry that comes immediately after another element. |
prevSiblingOf | Int | Narrows the query results to only the entry that comes immediately before another element. |
positionedAfter | Int | Narrows the query results to only entries that are positioned after another element. |
positionedBefore | Int | Narrows the query results to only entries that are positioned before another element. |
editable | Boolean | Whether to only return entries that the user has permission to edit. |
section | [String] | Narrows the query results based on the section handles the entries belong to. |
sectionId | [QueryArgument] | Narrows the query results based on the sections the entries belong to, per the sections’ IDs. |
type | [String] | Narrows the query results based on the entries’ entry type handles. |
typeId | [QueryArgument] | Narrows the query results based on the entries’ entry types, per the types’ IDs. |
authorId | [QueryArgument] | Narrows the query results based on the entries’ authors. |
authorGroup | [String] | Narrows the query results based on the user group the entries’ authors belong to. |
authorGroupId | [QueryArgument] | Narrows the query results based on the user group the entries’ authors belong to, per the groups’ IDs. |
postDate | [String] | Narrows the query results based on the entries’ post dates. |
before | String | Narrows the query results to only entries that were posted before a certain date. |
after | String | Narrows the query results to only entries that were posted on or after a certain date. |
expiryDate | [String] | Narrows the query results based on the entries’ expiry dates. |
# The globalSets
query
This query is used to query for global sets.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
handle | [String] | Narrows the query results based on the global sets’ handles. |
# The globalSet
query
This query is used to query for a single global set.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
handle | [String] | Narrows the query results based on the global sets’ handles. |
# The users
query
This query is used to query for users.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
email | [String] | Narrows the query results based on the users’ email addresses. |
username | [String] | Narrows the query results based on the users’ usernames. |
firstName | [String] | Narrows the query results based on the users’ first names. |
lastName | [String] | Narrows the query results based on the users’ last names. |
hasPhoto | Boolean | Narrows the query results to only users that have (or don’t have) a user photo. |
groupId | [QueryArgument] | Narrows the query results based on the user group the users belong to, per the groups’ IDs. |
group | [QueryArgument] | Narrows the query results based on the user group the users belong to. |
# The userCount
query
This query is used to return the number of users.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
email | [String] | Narrows the query results based on the users’ email addresses. |
username | [String] | Narrows the query results based on the users’ usernames. |
firstName | [String] | Narrows the query results based on the users’ first names. |
lastName | [String] | Narrows the query results based on the users’ last names. |
hasPhoto | Boolean | Narrows the query results to only users that have (or don’t have) a user photo. |
groupId | [QueryArgument] | Narrows the query results based on the user group the users belong to, per the groups’ IDs. |
group | [QueryArgument] | Narrows the query results based on the user group the users belong to. |
# The user
query
This query is used to query for a single user.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
email | [String] | Narrows the query results based on the users’ email addresses. |
username | [String] | Narrows the query results based on the users’ usernames. |
firstName | [String] | Narrows the query results based on the users’ first names. |
lastName | [String] | Narrows the query results based on the users’ last names. |
hasPhoto | Boolean | Narrows the query results to only users that have (or don’t have) a user photo. |
groupId | [QueryArgument] | Narrows the query results based on the user group the users belong to, per the groups’ IDs. |
group | [QueryArgument] | Narrows the query results based on the user group the users belong to. |
# The tags
query
This query is used to query for tags.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
group | [String] | Narrows the query results based on the tag groups the tags belong to per the group’s handles. |
groupId | [QueryArgument] | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. |
# The tagCount
query
This query is used to return the number of tags.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
group | [String] | Narrows the query results based on the tag groups the tags belong to per the group’s handles. |
groupId | [QueryArgument] | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. |
# The tag
query
This query is used to query for a single tag.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
group | [String] | Narrows the query results based on the tag groups the tags belong to per the group’s handles. |
groupId | [QueryArgument] | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. |
# The categories
query
This query is used to query for categories.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
withStructure | Boolean | Explicitly determines whether the query should join in the structure data. |
structureId | Int | Determines which structure data should be joined into the query. |
level | Int | Narrows the query results based on the elements’ level within the structure. |
hasDescendants | Boolean | Narrows the query results based on whether the elements have any descendants. |
ancestorOf | Int | Narrows the query results to only elements that are ancestors of another element. |
ancestorDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by ancestorOf . |
descendantOf | Int | Narrows the query results to only elements that are descendants of another element. |
descendantDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by descendantOf . |
leaves | Boolean | Narrows the query results based on whether the elements are “leaves” (element with no descendants). |
nextSiblingOf | Int | Narrows the query results to only the entry that comes immediately after another element. |
prevSiblingOf | Int | Narrows the query results to only the entry that comes immediately before another element. |
positionedAfter | Int | Narrows the query results to only entries that are positioned after another element. |
positionedBefore | Int | Narrows the query results to only entries that are positioned before another element. |
editable | Boolean | Whether to only return categories that the user has permission to edit. |
group | [String] | Narrows the query results based on the category groups the categories belong to per the group’s handles. |
groupId | [QueryArgument] | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. |
# The categoryCount
query
This query is used to return the number of categories.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
withStructure | Boolean | Explicitly determines whether the query should join in the structure data. |
structureId | Int | Determines which structure data should be joined into the query. |
level | Int | Narrows the query results based on the elements’ level within the structure. |
hasDescendants | Boolean | Narrows the query results based on whether the elements have any descendants. |
ancestorOf | Int | Narrows the query results to only elements that are ancestors of another element. |
ancestorDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by ancestorOf . |
descendantOf | Int | Narrows the query results to only elements that are descendants of another element. |
descendantDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by descendantOf . |
leaves | Boolean | Narrows the query results based on whether the elements are “leaves” (element with no descendants). |
nextSiblingOf | Int | Narrows the query results to only the entry that comes immediately after another element. |
prevSiblingOf | Int | Narrows the query results to only the entry that comes immediately before another element. |
positionedAfter | Int | Narrows the query results to only entries that are positioned after another element. |
positionedBefore | Int | Narrows the query results to only entries that are positioned before another element. |
editable | Boolean | Whether to only return categories that the user has permission to edit. |
group | [String] | Narrows the query results based on the category groups the categories belong to per the group’s handles. |
groupId | [QueryArgument] | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. |
# The category
query
This query is used to query for a single category.
Argument | Type | Description |
---|---|---|
id | [QueryArgument] | Narrows the query results based on the elements’ IDs. |
uid | [String] | Narrows the query results based on the elements’ UIDs. |
drafts | Boolean | Whether draft elements should be returned. |
draftOf | QueryArgument | The source element ID that drafts should be returned for. Set to false to fetch unsaved drafts. |
draftId | Int | The ID of the draft to return (from the drafts table) |
draftCreator | Int | The drafts’ creator ID |
revisions | Boolean | Whether revision elements should be returned. |
revisionOf | QueryArgument | The source element ID that revisions should be returned for |
revisionId | Int | The ID of the revision to return (from the revisions table) |
revisionCreator | Int | The revisions’ creator ID |
status | [String] | Narrows the query results based on the elements’ statuses. |
archived | Boolean | Narrows the query results to only elements that have been archived. |
trashed | Boolean | Narrows the query results to only elements that have been soft-deleted. |
site | [String] | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
siteId | String | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. |
unique | Boolean | Determines whether only elements with unique IDs should be returned by the query. |
enabledForSite | Boolean | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the site argument. |
title | [String] | Narrows the query results based on the elements’ titles. |
slug | [String] | Narrows the query results based on the elements’ slugs. |
uri | [String] | Narrows the query results based on the elements’ URIs. |
search | String | Narrows the query results to only elements that match a search query. |
relatedTo | [QueryArgument] | Narrows the query results to elements that relate to any of the provided element IDs. This argument is ignored, if relatedToAll is also used. |
relatedToAll | [QueryArgument] | Narrows the query results to elements that relate to all of the provided element IDs. Using this argument will cause relatedTo argument to be ignored. |
ref | [String] | Narrows the query results based on a reference string. |
fixedOrder | Boolean | Causes the query results to be returned in the order specified by the id argument. |
inReverse | Boolean | Causes the query results to be returned in reverse order. |
dateCreated | [String] | Narrows the query results based on the elements’ creation dates. |
dateUpdated | [String] | Narrows the query results based on the elements’ last-updated dates. |
offset | Int | Sets the offset for paginated results. |
limit | Int | Sets the limit for paginated results. |
orderBy | String | Sets the field the returned elements should be ordered by |
withStructure | Boolean | Explicitly determines whether the query should join in the structure data. |
structureId | Int | Determines which structure data should be joined into the query. |
level | Int | Narrows the query results based on the elements’ level within the structure. |
hasDescendants | Boolean | Narrows the query results based on whether the elements have any descendants. |
ancestorOf | Int | Narrows the query results to only elements that are ancestors of another element. |
ancestorDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by ancestorOf . |
descendantOf | Int | Narrows the query results to only elements that are descendants of another element. |
descendantDist | Int | Narrows the query results to only elements that are up to a certain distance away from the element specified by descendantOf . |
leaves | Boolean | Narrows the query results based on whether the elements are “leaves” (element with no descendants). |
nextSiblingOf | Int | Narrows the query results to only the entry that comes immediately after another element. |
prevSiblingOf | Int | Narrows the query results to only the entry that comes immediately before another element. |
positionedAfter | Int | Narrows the query results to only entries that are positioned after another element. |
positionedBefore | Int | Narrows the query results to only entries that are positioned before another element. |
editable | Boolean | Whether to only return categories that the user has permission to edit. |
group | [String] | Narrows the query results based on the category groups the categories belong to per the group’s handles. |
groupId | [QueryArgument] | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. |
# List of available directives
Directives are not regulated by permissions and they affect how the returned data is displayed.
# The formatDateTime
directive
This directive allows for formatting any date to the desired format. It can be applied to all fields, but changes anything only when applied to a DateTime field.
Argument | Type | Description |
---|---|---|
format | String | This specifies the format to use. This can be short , medium , long , full , an ICU date format (opens new window), or a PHP date format (opens new window). It defaults to the Atom date time format (opens new window). |
timezone | String | The full name of the timezone, defaults to UTC. (E.g., America/New_York) |
locale | String | The locale to use when formatting the date. (E.g., en-US) |
# The transform
directive
This directive is used to return a URL for an asset transform (opens new window). It accepts the same arguments you would use for a transform in Craft and adds the immediately
argument.
Argument | Type | Description |
---|---|---|
handle | String | The handle of the named transform to use. |
transform | String | The handle of the named transform to use. |
width | Int | Width for the generated transform |
height | Int | Height for the generated transform |
mode | String | The mode to use for the generated transform. |
position | String | The position to use when cropping, if no focal point specified. |
interlace | String | The interlace mode to use for the transform |
quality | Int | The quality of the transform |
format | String | The format to use for the transform |
immediately | Boolean | Whether the transform should be generated immediately or only when the image is requested used the generated URL |
# The markdown
directive
Parses the passed field value as Markdown.
Argument | Type | Description |
---|---|---|
flavor | String | The “flavor” of Markdown the input should be interpreted with. Accepts the same arguments as yii\helpers\Markdown::process(). |
inlineOnly | Boolean | Whether to only parse inline elements, omitting any <p> tags. |
# Pre-defined interfaces
Craft defines several interfaces to be implemented by the different GraphQL types.
# The AssetInterface
interface
This is the interface implemented by all assets.
Field | Type | Description |
---|---|---|
id | ID | The id of the entity |
uid | String | The uid of the entity |
_count | Int | Return a number of related elements for a field. |
title | String | The element’s title. |
slug | String | The element’s slug. |
uri | String | The element’s URI. |
enabled | Boolean | Whether the element is enabled or not. |
archived | Boolean | Whether the element is archived or not. |
siteId | Int | The ID of the site the element is associated with. |
language | String | The language of the site element is associated with. |
searchScore | String | The element’s search score, if the search parameter was used when querying for the element. |
trashed | Boolean | Whether the element has been soft-deleted or not. |
status | String | The element's status. |
dateCreated | DateTime | The date the element was created. |
dateUpdated | DateTime | The date the element was last updated. |
volumeId | Int | The ID of the volume that the asset belongs to. |
folderId | Int | The ID of the folder that the asset belongs to. |
filename | String | The filename of the asset file. |
extension | String | The file extension for the asset file. |
hasFocalPoint | Boolean | Whether a user-defined focal point is set on the asset. |
focalPoint | [Float] | The focal point represented as an array with x and y keys, or null if it's not an image. |
kind | String | The file kind. |
size | String | The file size in bytes. |
height | Int | The height in pixels or null if it's not an image. |
width | Int | The width in pixels or null if it's not an image. |
img | String | An <img> tag based on this asset. |
srcset | String | Returns a srcset attribute value based on the given widths or x-descriptors. |
url | String | The full URL of the asset. This field accepts the same fields as the transform directive. |
mimeType | String | The file’s MIME type, if it can be determined. |
path | String | The asset's path in the volume. |
dateModified | DateTime | The date the asset file was last modified. |
prev | AssetInterface | Returns the previous element relative to this one, from a given set of criteria. CAUTION: Applying arguments to this field severely degrades the performance of the query. |
next | AssetInterface | Returns the next element relative to this one, from a given set of criteria. CAUTION: Applying arguments to this field severely degrades the performance of the query. |
# The EntryInterface
interface
This is the interface implemented by all entries.
Field | Type | Description |
---|---|---|
id | ID | The id of the entity |
uid | String | The uid of the entity |
_count | Int | Return a number of related elements for a field. |
title | String | The element’s title. |
slug | String | The element’s slug. |
uri | String | The element’s URI. |
enabled | Boolean | Whether the element is enabled or not. |
archived | Boolean | Whether the element is archived or not. |
siteId | Int | The ID of the site the element is associated with. |
language | String | The language of the site element is associated with. |
searchScore | String | The element’s search score, if the search parameter was used when querying for the element. |
trashed | Boolean | Whether the element has been soft-deleted or not. |
status | String | The element's status. |
dateCreated | DateTime | The date the element was created. |
dateUpdated | DateTime | The date the element was last updated. |
lft | Int | The element’s left position within its structure. |
rgt | Int | The element’s right position within its structure. |
level | Int | The element’s level within its structure |
root | Int | The element’s structure’s root ID |
structureId | Int | The element’s structure ID. |
isDraft | Boolean | Returns whether this is a draft. |
isRevision | Boolean | Returns whether this is a revision. |
sourceId | Int | Returns the element’s ID, or if it’s a draft/revision, its source element’s ID. |
sourceUid | String | Returns the element’s UUID, or if it’s a draft/revision, its source element’s UUID. |
draftId | Int | The ID of the draft to return (from the drafts table) |
isUnsavedDraft | Boolean | Returns whether this is a draft. |
draftName | String | The name of the draft. |
draftNotes | String | The notes for the draft. |
sectionId | Int | The ID of the section that contains the entry. |
sectionHandle | String | The handle of the section that contains the entry. |
typeId | Int | The ID of the entry type that contains the entry. |
typeHandle | String | The handle of the entry type that contains the entry. |
postDate | DateTime | The entry's post date. |
expiryDate | DateTime | The expiry date of the entry. |
children | [EntryInterface] | The entry’s children, if the section is a structure. Accepts the same arguments as the entries query. |
parent | EntryInterface | The entry’s parent, if the section is a structure. |
url | String | The element’s full URL |
localized | [EntryInterface] | The same element in other locales. |
prev | EntryInterface | Returns the previous element relative to this one, from a given set of criteria. CAUTION: Applying arguments to this field severely degrades the performance of the query. |
next | EntryInterface | Returns the next element relative to this one, from a given set of criteria. CAUTION: Applying arguments to this field severely degrades the performance of the query. |
# The GlobalSetInterface
interface
This is the interface implemented by all global sets.
Field | Type | Description |
---|---|---|
id | ID | The id of the entity |
uid | String | The uid of the entity |
_count | Int | Return a number of related elements for a field. |
title | String | The element’s title. |
slug | String | The element’s slug. |
uri | String | The element’s URI. |
enabled | Boolean | Whether the element is enabled or not. |
archived | Boolean | Whether the element is archived or not. |
siteId | Int | The ID of the site the element is associated with. |
language | String | The language of the site element is associated with. |
searchScore | String | The element’s search score, if the search parameter was used when querying for the element. |
trashed | Boolean | Whether the element has been soft-deleted or not. |
status | String | The element's status. |
dateCreated | DateTime | The date the element was created. |
dateUpdated | DateTime | The date the element was last updated. |
name | String | The name of the global set. |
handle | String | The handle of the global set. |
# The MatrixBlockInterface
interface
This is the interface implemented by all matrix blocks.
Field | Type | Description |
---|---|---|
id | ID | The id of the entity |
uid | String | The uid of the entity |
_count | Int | Return a number of related elements for a field. |
title | String | The element’s title. |
slug | String | The element’s slug. |
uri | String | The element’s URI. |
enabled | Boolean | Whether the element is enabled or not. |
archived | Boolean | Whether the element is archived or not. |
siteId | Int | The ID of the site the element is associated with. |
language | String | The language of the site element is associated with. |
searchScore | String | The element’s search score, if the search parameter was used when querying for the element. |
trashed | Boolean | Whether the element has been soft-deleted or not. |
status | String | The element's status. |
dateCreated | DateTime | The date the element was created. |
dateUpdated | DateTime | The date the element was last updated. |
fieldId | Int | The ID of the field that owns the matrix block. |
ownerId | Int | The ID of the element that owns the matrix block. |
typeId | Int | The ID of the matrix block's type. |
typeHandle | String | The handle of the matrix block's type. |
sortOrder | Int | The sort order of the matrix block within the owner element field. |
# The UserInterface
interface
This is the interface implemented by all users.
Field | Type | Description |
---|---|---|
id | ID | The id of the entity |
uid | String | The uid of the entity |
_count | Int | Return a number of related elements for a field. |
title | String | The element’s title. |
slug | String | The element’s slug. |
uri | String | The element’s URI. |
enabled | Boolean | Whether the element is enabled or not. |
archived | Boolean | Whether the element is archived or not. |
siteId | Int | The ID of the site the element is associated with. |
language | String | The language of the site element is associated with. |
searchScore | String | The element’s search score, if the search parameter was used when querying for the element. |
trashed | Boolean | Whether the element has been soft-deleted or not. |
status | String | The element's status. |
dateCreated | DateTime | The date the element was created. |
dateUpdated | DateTime | The date the element was last updated. |
photo | AssetInterface | The user's photo. |
friendlyName | String | The user's first name or username. |
fullName | String | The user's full name. |
name | String | The user's full name or username. |
preferences | String | The user’s preferences. |
preferredLanguage | String | The user’s preferred language. |
username | String | The username. |
firstName | String | The user's first name. |
lastName | String | The user's last name. |
email | String | The user's email. |
# The CategoryInterface
interface
This is the interface implemented by all categories.
Field | Type | Description |
---|---|---|
id | ID | The id of the entity |
uid | String | The uid of the entity |
_count | Int | Return a number of related elements for a field. |
title | String | The element’s title. |
slug | String | The element’s slug. |
uri | String | The element’s URI. |
enabled | Boolean | Whether the element is enabled or not. |
archived | Boolean | Whether the element is archived or not. |
siteId | Int | The ID of the site the element is associated with. |
language | String | The language of the site element is associated with. |
searchScore | String | The element’s search score, if the search parameter was used when querying for the element. |
trashed | Boolean | Whether the element has been soft-deleted or not. |
status | String | The element's status. |
dateCreated | DateTime | The date the element was created. |
dateUpdated | DateTime | The date the element was last updated. |
lft | Int | The element’s left position within its structure. |
rgt | Int | The element’s right position within its structure. |
level | Int | The element’s level within its structure |
root | Int | The element’s structure’s root ID |
structureId | Int | The element’s structure ID. |
groupId | Int | The ID of the group that contains the category. |
groupHandle | String | The handle of the group that contains the category. |
children | [CategoryInterface] | The category’s children. |
parent | CategoryInterface | The category’s parent. |
url | String | The element’s full URL |
localized | [CategoryInterface] | The same element in other locales. |
prev | CategoryInterface | Returns the previous element relative to this one, from a given set of criteria. CAUTION: Applying arguments to this field severely degrades the performance of the query. |
next | CategoryInterface | Returns the next element relative to this one, from a given set of criteria. CAUTION: Applying arguments to this field severely degrades the performance of the query. |
# The TagInterface
interface
This is the interface implemented by all tags.
Field | Type | Description |
---|---|---|
id | ID | The id of the entity |
uid | String | The uid of the entity |
_count | Int | Return a number of related elements for a field. |
title | String | The element’s title. |
slug | String | The element’s slug. |
uri | String | The element’s URI. |
enabled | Boolean | Whether the element is enabled or not. |
archived | Boolean | Whether the element is archived or not. |
siteId | Int | The ID of the site the element is associated with. |
language | String | The language of the site element is associated with. |
searchScore | String | The element’s search score, if the search parameter was used when querying for the element. |
trashed | Boolean | Whether the element has been soft-deleted or not. |
status | String | The element's status. |
dateCreated | DateTime | The date the element was created. |
dateUpdated | DateTime | The date the element was last updated. |
groupId | Int | The ID of the group that contains the tag. |
groupHandle | String | The handle of the group that contains the tag. |
# Mutations
The actual API features will depend on what your schema allows.
Mutations in GraphQL provide a way of modifying data. The actual mutations will vary depending on the schema. There are some common mutations per GraphQL object type as well as type-specific mutations.
Mutations take the data as arguments. While they’re mostly straightforward, there are a few important cases to consider.
# Matrix Fields in Mutations
GraphQL’s limited input types can be challenging with complex Matrix fields.
We recommend reading how to save matrix field data in entry forms first if you’ve not saved matrix field form data.
Matrix input types generally have the following structure:
Field | Description |
---|---|
sortOrder | A list of all the block IDs that you wish the Matrix field to persist after the mutation in the required order. This include any new blocks. |
blocks | A list of all the actual blocks. You don’t have to include any blocks that are not modified, however, they must be represented on the sortOrder field if you don’t want them deleted. |
An actual block input type will contain fields for all the possible block types for this field, however, the first non-empty block will be considered in the order that the block types are defined on the field.
Let’s look at an example.
Say you have a Matrix field with a handle documentationField
. The field has two block types: screenshot
and paragraph
. The following is a list of all the input types generated for this Matrix field.
Type name | Type Description |
---|---|
documentationField_MatrixInput | This is the input type for the Matrix field. As discussed above, it will contain two fields: sortOrder and blocks . |
documentationField_MatrixBlockContainerInput | This is the input type that represents the block. In this case it will contain two fields: screenshot and paragraph . |
documentationField_screenshot_MatrixBlockInput | This is the input type for the screenshot block. It will contain all the fields defined for that block type. |
documentationField_paragraph_MatrixBlockInput | In a similar fashion, this is the input type for the paragraph block. |
In GraphQL SDL it would look like this:
input docunentationField_MatrixInput {
sortOrder: [QueryArgument]!
blocks: [documentationField_MatrixBlockContainerInput]
}
input documentationField_MatrixBlockContainerInput {
screenshot: documentationField_screenshot_MatrixBlockInput
paragraph: documentationField_paragraph_MatrixBlockInput
}
input documentationField_screenshot_MatrixBlockInput {
# List of content fields defined for this block type
}
input documentationField_paragraph_MatrixBlockInput {
# List of content fields defined for this block type
}
To submit two blocks, the blocks
would contain a list of two input objects of the documentationField_MatrixBlockContainerInput
input type. What field on those objects would contain data would determine the final block type. If more than one of the block types are defined, only the block type that is listed first will be considered.
# Uploading files via mutations
You can upload a file in one of two ways: pass a URL to be downloaded to the server, or pass Base64-encoded file data. Using either approach, you’ll need to use the FileInput
GraphQL input type which has the following fields:
Field | Description |
---|---|
fileData | The contents of the file in Base64 format. If provided, takes precedence over the URL. |
filename | The filename to use for the file. If not present, Craft will figure out a filename on its own. |
url | The URL of the file to use |
# Mutating Entries
# Saving an Entry
To save an entry, use the entry type-specific mutation which will have the name in the form of save_<sectionHandle>_<entryTypeHandle>_Entry
:
Argument | Type | Description |
---|---|---|
id | ID | Set the element’s ID. |
uid | String | Set the element’s UID. |
title | String | The title of the element. |
enabled | Boolean | Whether the element should be enabled. |
authorId | ID | The ID of the user that created this entry. |
postDate | DateTime | When should the entry be posted. |
expiryDate | DateTime | When should the entry expire. |
slug | String | Narrows the query results based on the elements’ slugs. |
siteId | Int | Determines which site(s) the elements should be saved to. Defaults to the primary site. |
... | More arguments depending on the field layout for the type |
The id
, uid
and authorId
arguments do no exist for single entries. This is because single entries have no authors and are identified already by the exact mutation. In a similar fashion, there are additional arguments available for structured entries. For more information, refer to mutating structure data.
After saving an entry, Craft runs queue jobs for updating revisions and search indexes. If you’re using Craft headlessly or infrequently accessing the control panel, consider disabling runQueueAutomatically and establishing an always-running daemon (opens new window) to keep revisions and search indexes up to date.
# Editing Existing Entries
You can modify existing entries by passing the populated id
argument to your mutation.
# Saving a Draft
To save a draft for an entry, use the entry type-specific mutation which will have the name in the form of save_<sectionHandle>_<entryTypeHandle>_Draft
:
Argument | Type | Description |
---|---|---|
title | String | The title of the element. |
enabled | Boolean | Whether the element should be enabled. |
authorId | ID | The ID of the user that created this entry. |
postDate | DateTime | When should the entry be posted. |
expiryDate | DateTime | When should the entry expire. |
slug | String | Narrows the query results based on the elements’ slugs. |
siteId | Int | Determines which site(s) the elements should be saved to. Defaults to the primary site. |
draftId | ID! | The ID of the draft. |
draftName | String | The name of the draft. |
draftNotes | String | Notes for the draft. |
... | More arguments depending on the field layout for the type |
# Creating or Publishing a Draft
To create a draft use the createDraft
mutation., which requires the id
of the entry for which to create the draft as an argument and returns the resulting id of the draft as the result.
For publishing a draft, you should use the publishDraft
mutation, which requires the id
of the draft to publish as an argument and returns the id of the entry it belongs to as the result.
# Deleting an Entry
To delete an entry use the deleteEntry
mutation, which requires the id
of the entry that must be deleted. It returns a boolean value as the result to indicate whether the operation was successful.
# Mutating Assets
# Saving an Asset
To create or update an asset use the volume-specific mutation, which will have the name in the form of save_<volumeHandle>_Asset
:
Argument | Type | Description |
---|---|---|
id | ID | Set the element’s ID. |
uid | String | Set the element’s UID. |
title | String | The title of the element. |
enabled | Boolean | Whether the element should be enabled. |
_file | FileInput | The file to use for this asset |
newFolderId | ID | ID of the new folder for this asset |
... | More arguments depending on the field layout for the type |
# Deleting an Asset
To delete an asset use the deleteAsset
mutation, which requires the id
of the asset that must be deleted. It returns a boolean value as the result to indicate whether the operation was successful.
# Mutating Tags
# Saving a Tag
To create or update a tag use the tag group-specific mutation, which will have the name in the form of save_<tagGroupHandle>_Tag
:
Argument | Type | Description |
---|---|---|
id | ID | Set the element’s ID. |
uid | String | Set the element’s UID. |
title | String | The title of the element. |
enabled | Boolean | Whether the element should be enabled. |
... | More arguments depending on the field layout for the type |
# Deleting a Tag
To delete a tag use the deleteTag
mutation, which requires the id
of the tag that must be deleted. It returns a boolean value as the result to indicate whether the operation was successful.
# Mutating Categories
# Saving a Category
To create or update a category use the category group-specific mutation, which will have the name in the form of save_<categoryGroupHandle>_Tag
.
Argument | Type | Description |
---|---|---|
id | ID | Set the element’s ID. |
uid | String | Set the element’s UID. |
title | String | The title of the element. |
enabled | Boolean | Whether the element should be enabled. |
... | More arguments depending on the field layout for the type |
# Deleting a Category
To delete a category use the deleteCategory
mutation, which requires the id
of the category that must be deleted. It returns a boolean value as the result to indicate whether the operation was successful.
# Mutating Structure Data
Entries that belong to a structure section and categories are parts of structure. To manipulate their place in the structure, just save the elements using the appropriate mutations and use the following arguments.
Argument | Type | Description |
---|---|---|
prependTo | ID | The ID of the element to prepend to. |
appendTo | ID | The ID of the element to append to. |
prependToRoot | Boolean | Whether to prepend this element to the root. |
appendToRoot | Boolean | Whether to append this element to the root. |
insertBefore | ID | The ID of the element this element should be inserted before. |
insertAfter | ID | The ID of the element this element should be inserted after. |
# Mutating Global Sets
To update a global set use the appropriate mutations which will have the name in the form of save_<globalSetHandle>_GlobalSet
.
The only available arguments are custom fields on the global set.
# Mutating Users
Mutating users with Craft native GraphQL API is currently not possible.