GraphQL is a query language that prioritizes giving clients the data they request and no more. Compared to the Delivery REST API, the Delivery GraphQL API exposes only a single endpoint for making queries.
Each Kontent.ai environment has its own GraphQL schema generated from the environment's content model. The schema is generated dynamically at the request time and is always current.The Delivery GraphQL API is a read-only API. The GraphQL API accepts GET and POST requests to the base URL https://graphql.kontent.ai/<YOUR_ENVIRONMENT_ID>.Use the API to deliver specific content to your website or app. The API responses are cached in a CDN. This makes the content quickly available from wherever you are.
You can make queries to the Delivery GraphQL API using either POST or GET requests. For both POST and GET requests, the base URL is the same. The difference is in how you specify your GraphQL query. The following examples show how to
for a specific article using POST and GET requests.
For POST requests, specify your GraphQL query in the body of your HTTP request. The maximum request body size is 8 kB.
For GET requests, specify your GraphQL query using the query parameter named query. With query parameters, you’re limited by the maximum URL length of 2000 characters.
By default, Delivery GraphQL API doesn’t require authentication. If you enable secure access for your Kontent.ai environment or want to preview content, you need to authenticate your requests with a Delivery API key.
To create Delivery API keys, you need to be a Project manager. When creating the API key, you can limit the API key scope to specific environments.
To authenticate your API requests, add the Authorization header to your request in the following format: Authorization: Bearer <YOUR_API_KEY>. Requests with an incorrect or missing Authorization header will fail with an error.
To get the latest version of your content items from your project’s environment, you need to use the preview base URL and authenticate your requests with a valid Delivery API key. To create Delivery API keys, you need to be a Project manager.
GraphiQL supports specifying custom headers, which you can use to make API calls to environments with secure access enabled or to preview content.
Requests made to the Delivery GraphQL API count towards the overall API Calls limit set in our Fair Use Policy. This includes requests for both published and unpublished content.
There is no limit on the total number of API calls you can make.
Before processing your query, the GraphQL API calculates the following:
If your query complexity exceeds 2000, the GraphQL API rejects your request and returns a QUERY_TOO_COMPLEXerror.
You can find whether your requests are close to the complexity limit by looking at the X-Complexity header.
Example 1
The following query can return up to 1,000 Articles. Its complexity is 1,000.
Example 2
The following query can return:
Up to 100 Articles – complexity is 100
Up to 20 linked content items for each Article – complexity is 100 × 20
The total complexity of the query is 2100.
The depth of each query starts at level zero. If your query exceeds the nesting limit of 124, the GraphQL API rejects your request and returns an error.
Example 1
The total depth of the following query is 5. The root query in the API request goes five levels deep, with the first level counted as zero.
Example 2
The total depth of the following query is 4. The two root queries both go two levels deep. The sum of the maximum depth of the root queries is 4.
The GraphQL API enforces a rate limitation based on resource consumption.
For cached requests served from our CDN, we don't enforce any rate limits. You can make an unlimited number of repeated requests to the CDN.
For uncached requests that reach the GraphQL API, we enforce a rate limitation of 2,000 resource units per second and 40,000 resource units per minute. To see how many resources your requests consumed, check the X-Request-Charge header.
When you reach the resource limit for a given time period, the API rejects the request and responds with a 429 HTTP error. This error comes with the Retry-After header that tells you how many seconds you need to wait before retrying your request. Each failed request is perfectly safe to retry. If you begin to receive 429 errors, reduce the frequency of your requests.
In addition to the above, a CDN-level protective layer is in place by Fastly to filter out potentially disruptive traffic before it reaches the API. These limits are based on the number of uncached requests, regardless of their resource usage:
1,000 requests per second
5,000 requests per 10 seconds
15,000 requests per minute
Cached responses are not subject to these limits and don’t affect normal usage.
The Delivery GraphQL API returns standard HTTP status codes to indicate the success or failure of a request. In general, status codes in the 2xx range indicate a successful request, status codes in the 4xx range indicate errors caused by an incorrect input (for example, providing an incorrect API key), and status codes in the 5xx range indicate an error on our side.
If your query contains a mistake, the API might return a 200 with an error message in the response body.
Status code
Description
200 OK
The request was successful. However, the API might return an error message. For example, if your query is too complex or fails to execute correctly.
400 Bad Request
The request wasn't successful. Check your request for a missing required parameter or an invalid query parameter value.
403 Forbidden
The API request was forbidden. Check if your subscription plan comes with GraphQL enabled.
For every content type in your project's environment, the API generates two GraphQL root queries. For example, for a content type named Article, you get the following queries:
Both of these queries work with a GraphQL type named Article that is generated from the content type.
To get a single content item, you need to provide the item's type and the item's identifier. The identifier can be either a codename or an internal ID.
To get a list of content items, you need to use the <typeName>_All (as in article_All) query. By default, the items are ordered alphabetically by codename.
If you want to get your items in a specific order, use the order argument in your query. The order argument requires that you provide a field name and specify whether the order is ascending or descending.
By default, the GraphQL API returns content in the default language. To get content items in a specific language, use the languageFilter argument in your queries.
If the requested content items don't have content in the specified language, the API follows language fallbacks as specified in your localization settings. To check the language of the returned content items, specify the language field of the content item's system_ object.
To retrieve content items based on specific criteria, you can filter the content items using the where argument. The where argument can be applied only to root collection queries, which are based on your content types such as article_All, navigationItem_All, and so on.
In the where argument, you can specify a single condition with one filter or combine multiple filters using the AND and OR operators.
To filter by content item metadata, you can use the following _system_ fields:
id(string)
codename(string)
name (string)
lastModified (string)
collection (string)
workflow (string)
workflowStep (string)
language (LanguageFilter!)
To filter by the values of elements within content items, you can use fields that are based on the following content elements
Date & time (value field only)
Linked items
Multiple choice
Number
Text
Taxonomy
You can use the following filters on specific system fields and element fields.
Filter
Description
Example condition
Use with types
eq
Checks whether the field value matches exactly to the specified filter value.
where: {title: {eq: "My article"}}where: {_system_: {id: {eq: "<item-id>"}}}
DateTime, Number, String
notEq
Checks if the field value is different than the specified value.
To combine multiple filters in your where arguments, you can use the AND and OR operators. Both operators take an array of at least two values and can be nested in one another.
To paginate through collection fields, use the limit and offset arguments combined with the predefined totalCount field.
limit (Int) – Specifies the number of objects to retrieve. If not specified, the API returns up to 10 objects. The maximum limit value is 1,000.
offset (Int) – Specifies the number of objects to skip. If not specified, the offset is 0, and the API returns the first page of results.
The GraphQL schema for your Kontent.ai environment is dynamically generated based on your content model. The schema is generated at request time and is always current. This also means that any changes to your content model will affect your GraphQL schemas.
The names of fields and types in your GraphQL schema are generated from the codenames of your content types, content type snippets
The original codename is stripped of underscores (_), converted to PascalCase, and used as a GraphQL name. For content type snippets, the converted codename is prefixed with an underscore. For date & time elements, the converted codename is suffixed with string _with_timezone.
The GraphQL type names and field names must be unique. If two codenames lead to an identical GraphQL name, the GraphQL schema fails to build correctly. For example, the codenames button and button_ would lead to the same GraphQL name. In such case, adjust your codenames to avoid collisions.
Examples of codename conversion to GraphQL names:
Original codename
GraphQL object type name
GraphQL query name
Content type article
Article for single itemArticle_All for multiple items
article for single item article_All for multiple items
When retrieving lists of objects using collection fields, you need to specify the items field and at least one of its subfields. You can also specify the predefined totalCount field to find how many items the collection contains.
Every GraphQL type for retrieving content items consists of the following fields:
The predefined _system_ field with the content item's metadata.
The individual fields for every content element as defined by the item's content type.
For example, the following is a GraphQL type for the content type named Article.
Some of the GraphQL types come with the _system_ field. The _system_ field is defined by the _Sys type, which contains your content items' metadata. For example, the content item's last modification date, codename, and so on.
The _Sys type is used in the GraphQL types generated from your content types.
You'll also find the _system_ field in the predefined system GraphQL types such as _Language, _ContentType, _Collection, _Workflow, and _WorkflowStep. In these types, the _system_ field contains partial metadata such as the object's name or codename.
Assets have two predefined GraphQL types. The used type differs based on whether the asset itself is used in asset elements or rich text elements
When the asset is used in asset elements, the schema uses the predefined _Asset type. The _Asset type contains the renditions field referencing customized images.
To display customized images on the website or an app, you first need to apply custom query parameters to the asset's original URL.
When the asset is used in rich text elements, the schema uses the predefined _RichTextAsset type. The _RichTextAsset type has with an additional field named imageId. The imageId field helps you identify the assets that are referenced in the rich text's html field.
Content type snippets are transformed into separate GraphQL types whose name is prefixed with an underscore character (_). To query the elements of the snippet, you need to specify the subfields of the snippet field.
For example, a snippet named Metadata will have the following GraphQL type.
Custom elements are transformed into a GraphQL type with a single value field.
Date & time elements are transformed into GraphQL type with value and display_timezone fields.
The value field contains an ISO-8610 formatted string such as 2021-11-18T08:43:19Z. Time in this field is displayed and interpreted as UTC.
The display_timezone field contains an IANA time zone name such as Europe/Berlin. This information is used to display the time offset of the date & time element in the UI. The time zone doesn't modify the date specified in the value field. Check the full list of supported time zones.
The data type of the linkedItems, components and itemHyperlinks fields can change depending on the limitations set for the rich text element. With no limitations set for the type of linked items, components, and item links, the GraphQL type for rich text is the following.
If the components, linked items, or item links you can insert into rich text are limited to a specific content type, the GraphQL API reflects the limitation by generating several custom types.
For example, if the Body copy rich text element in an Article content type has the components and linked items limited to a content type named Tweet, you'll see the following GraphQL types.
Query total depth level – The sum of maximum nesting levels of the queries in your API request. The maximum query depth is 124. See query depth examples.
404
Not Found
The specified environment doesn't exist.
405 Method Not Allowed
The requested HTTP method is not supported for the specified resource.
429 Too Many Requests
The rate limit for the API has been exceeded, triggering a 5-minute block for the originating IP address. Try your request again after waiting the number of seconds shown in the Retry-After header.
5xx Internal Error or Service Unavailable
Something went wrong on our side. Try your request again after a few seconds and use a retry policy.
query GetOrderedItems { # Get articles ordered by their title from Z to A article_All(order: {title: desc}) { items { title } } # Blog posts ordered by codename from A to Z post_All(order: {_system_: {codename: asc}}) { items { title } }}
GraphQL
query GetSpanishArticles { # Requests articles in Spanish article_All(languageFilter: {languageCodename: "es-ES"}) { items { _system_ { language { _system_ { codename } } } title slug } }}
# Paginating articlesquery GetPaginatedArticles { article_All(limit: 10, offset: 10) { items { title } offset # Returns the specified offset limit # Returns the specified limit totalCount # Returns the total number of content items that match the query }}# Paginating linked content in rich textquery GetPaginatedLinkedItems { article_All { items { bodyCopy { html linkedItems(offset: 10, limit: 10) { items { _system_ { codename } } offset # Returns the specified offset limit # Returns the specified limit totalCount # Returns the total number of content items that match the query } } } }}
query HowToQueryCollectionFields { article_All { items { teaserImage { items { name } totalCount # Returns the total number of assets inserted in the asset element } personas { items { _system_ { codename } } totalCount # Returns the total number of selected taxonomy terms } relatedArticles { items { ... on Article { title } } totalCount # Returns the total number of items linked in the element } } totalCount # Returns the total number of articles matching the query }}
GraphQL
type Article implements _Item { _system_: _Sys! # The content item's metadata. title: String! # Text element teaserImage( # Asset element offset: Int = 0 limit: Int = 10 ): _AssetCollection! postDate_with_timezone: _DateAndTime # Date & time element bodyCopy: _RichText! # Rich text element relatedArticles( # Linked items element offset: Int = 0 limit: Int = 10 ): _ItemCollection! personas( # Taxonomy element offset: Int = 0 limit: Int = 10 ): _TaxonomyTermCollection! urlPattern: String! # URL slug element}
GraphQL
type _Sys { name: String! # The content item's display name. codename: String! # The content item's codename. language: _Language! # Metadata of the content item's language. type: _ContentType! # Metadata of the content item's content type. lastModified: DateTime! # ISO-8601 formatted date and time of the last change to user-content of the content item. The value is not affected when moving content items through workflow steps. collection: _Collection! # Metadata of the content item's collection. workflow: _Workflow! # Metadata of the content item's current workflow. workflowStep: _WorkflowStep! # Metadata of the content item's current workflow step. id: Guid! # The content item's internal ID.}
GraphQL
type _Collection { _system_: _CollectionSys! # The collection's predefined system fields.}type _CollectionSys { codename: String! # The collection's codename.}type _ContentType { _system_: _ContentTypeSys! # The content type's predefined system fields.}type _ContentTypeSys { name: String! # The content type's display name. codename: String! # The content type's codename.}type _Language { _system_: _LanguageSys! # The language's predefined system fields.}type _LanguageSys { name: String! # The language's display name. codename: String! # The language's codename.}type _Workflow { _system_: _WorkflowSys! # The workflow's predefined system fields.}type _WorkflowSys { codename: String! # The workflow's codename.}type _WorkflowStep { _system_: _WorkflowStepSys! # The workflow step's predefined system fields.}type _WorkflowStepSys { codename: String! # The workflow step's codename.}
GraphQL
type _Asset implements _AssetInterface { renditions: _AssetRenditionCollection # List of renditions available for this asset. url: String! # The asset's absolute URL. name: String # The asset's display name. description: String # The asset's alt text description for a specific language. type: String # The file's MIME type. size: Int # The file's size in bytes. width: Int # The image's width in pixels. height: Int # The image's height in pixels.}type _AssetRenditionCollection { offset: Int! limit: Int! totalCount: Int! items: [_Rendition!]! # Individual asset rendition objects.}type _Rendition { preset: String! # The image preset's codename. preset_id: String! # The image preset's ID. rendition_id: String! # The rendition's ID. query: String! # Parameters set for the image rendition. Need to be concatenated with the original asset's URL to customize the image. width: Int! # The rendition's width. height: Int! # The rendition's height.}
GraphQL
type _RichTextAsset implements _AssetInterface { imageId: String! # Identifier of the asset as used in the rich text element. url: String! # The asset's absolute URL. name: String # The asset's display name. description: String # The asset's alt text description for a specific language. type: String # The file's MIME type. size: Int # The file's size in bytes. width: Int # The image's width in pixels. height: Int # The image's height in pixels.}
GraphQL
type Metadata { metaTitle: String! metaDescription: String!}type Article implements _Item { _system_: _Sys! # The content item's predefined system fields. ... _metadata: Metadata! # The Metadata type with subfields for each element in the snippet}
GraphQL
type _CustomElement { value: String # The custom element's value as a string.}
GraphQL
type _DateAndTime { value: DateTime # The element's datetime output. display_timezone: String # The element's display timezone.}
GraphQL
type Article implements _Item { _system_: _Sys! # The content item's predefined system fields. ... relatedContent: _ItemCollection! # Linked items element without content type limitation}
GraphQL
type Article implements _Item { _system_: _Sys! # The content item's predefined system fields. ... relatedArticle: Article # Linked items element limited to a single Article content type relatedArticles: Article_RelatedArticles_Collection! # Linked items element limited Article content types}type Article_RelatedArticles_Collection { offset: Int! limit: Int! items: [Article!]!}
GraphQL
type _MultipleChoiceOptionCollection { offset: Int! limit: Int! items: [_MultipleChoiceOption!]! # Specifies the selected multiple choice options.}type _MultipleChoiceOption { _system_: _MultipleChoiceOptionSys! # The multiple choice option's predefined system fields.}type _MultipleChoiceOptionSys { name: String! # The multiple choice option's display name. codename: String! # The multiple choice option's codename.}
GraphQL
type Article implements _Item { _system_: _Sys! # The content item's predefined system fields. ... bodyCopy: _RichText! # Rich text element without type limitations}type _RichText { html: String! # The rich text's HTML output. Contains references to assets, links to content items, linked content, and components. itemHyperlinks: _ItemCollection! # Contains the content items referenced in hyperlinks. assets: _RichTextAssetCollection! # Contains the assets inserted into the rich text. linkedItems: _ItemCollection! # Contains the content items inserted into the rich text. components: _ItemCollection! # Contains the components inserted into the rich text.}
GraphQL
type Article implements _Item { _system_: _Sys! # The content item's predefined system fields. ... bodyCopy: Article_BodyCopy! # Rich text element with custom type limitations}type Article_BodyCopy { html: String! itemHyperlinks: _ItemCollection! assets: _RichTextAssetCollection! components: Article_BodyCopy_Components_Collection! linkedItems: Article_BodyCopy_LinkedItems_Collection!}type Article_BodyCopy_Components_Collection { offset: Int! limit: Int! items: [Tweet!]!}type Article_BodyCopy_LinkedItems_Collection { offset: Int! limit: Int! items: [Tweet!]!}
GraphQL
type _TaxonomyTermCollection { offset: Int! limit: Int! items: [_TaxonomyTerm!]! # Specifies the selected taxonomy terms.}type _TaxonomyTerm { _system_: _TaxonomyTermSys! # The taxonomy term's predefined system fields.}type _TaxonomyTermSys { name: String! # The taxonomy term's display name. codename: String! # The taxonomy term's codename.}
Delivery GraphQL API reference | Kontent.ai Learn
Explore your path to mastery
Say Hello World and learn the basics of getting and filtering content.
Not familiar with GraphQL?If you're starting out with GraphQL, we recommend you first learn the fundamentals in How to GraphQL.
Request body format depends on the content-type headerWith the content-type header set to application/graphql, you need to provide your GraphQL query directly in the request body. If you set the header to application/json, wrap your GraphQL query in valid JSON like this {"query":"{<YOUR_GRAPHQL_QUERY>}"}.
Reserved field namesThe codenames of your types, snippets, or elements must not be one of the following: Array, Boolean, DateTime, Float, Guid, Int, String.
Jan Cerman
37 minutes
Delivery API
in your browser.
