Delivery GraphQL API reference

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.

Introduction

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.

Make POST or GET requests

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 query for a specific article using POST and GET requests.

POST request

For POST requests, specify your GraphQL query in the body of your HTTP request. The maximum request body size is 8 kB.

GET request

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.

Authentication

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.

Preview content

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. When making preview requests, use the following:

• Preview base URL: https://preview-graphql.kontent.ai/<YOUR_ENVIRONMENT_ID>
• Authorization: Add the Authorization header to your request in the following format: Authorization: Bearer <YOUR_PREVIEW_API_KEY>.

Explore your GraphQL schema

You can explore your GraphQL schema in your web browser with GraphiQL online. 

1. Open GraphiQL online in your browser.
2. Enter the GraphQL base URL of your environment.
3. Start sending queries.

GraphiQL supports specifying custom headers, which you can use to make API calls to environments with secure access enabled or to preview content.

API limitations

API requests limit

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.

Query complexity limit

Before processing your query, the GraphQL API calculates the following:

• Query complexity – The maximum number of content items and components your query can return. The maximum complexity is 2000. See query complexity examples.
• 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.

Query complexity examples

If your query complexity exceeds 2000, the GraphQL API rejects your request and returns a QUERY_TOO_COMPLEX error. 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.

Query total depth limit examples

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.

Rate limitation

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.

Errors

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.

Query content

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:

• article query for retrieving a single content item.
• article_All collection query for retrieving multiple content items.

Both of these queries work with a GraphQL type named Article that is generated from the content type.

Get a content item

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.

List content items

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.

Order content items

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.   

Get localized content

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.

Filter content

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.

Filterable fields

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

Filters

You can use the following filters on specific system fields and element fields.

Combine filters with AND and OR

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.

Paging

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.

Schemas

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.

How schema names are generated

The names of fields and types in your GraphQL schema are generated from the codenames of your content types, content type snippets, and the elements that define them. 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:

Collection fields

The collection fields in the GraphQL schema can hold objects such as content items, assets, taxonomy terms, linked items, and more. You can use filters and paging on the collection fields to specify what kind of objects you want. 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.

Content items

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.

System metadata in the _system_ fields

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.

Partial system metadata

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.

Content element schemas

Assets

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. Both types define a set of common fields: url, name, description, type, size, width, and height.

Assets in asset 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.

Assets in rich text elements

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 snippet

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 element

Custom elements are transformed into a GraphQL type with a single value field.

Date and time element

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.

Linked items element

Linked items elements are transformed into GraphQL collection fields. If the linked items element is limited to a specific content type, the GraphQL field's data type reflects the limitation.

Multiple choice element

Multiple choice elements are transformed into a GraphQL collection field that lets you query the selected multiple choice options.

Number element

Number elements are transformed into GraphQL Float fields.

Rich text element

Rich text elements have a predefined GraphQL type, which contains the html, itemHyperlinks, linkedItems, components, and assets fields. For an overview of the HTML5 tags you might get in the html string field, check HTML5 elements allowed in rich text. 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.

Taxonomy element

Taxonomy elements are transformed into a GraphQL collection field that lets you query the selected taxonomy terms.

Text element

Text elements are transformed into GraphQL String fields. These fields contain plaintext.

URL slug element

URL slug elements are transformed into GraphQL String fields. These fields contain plaintext.