Use Delivery API to deliver large amounts of content to your website or app. Your content is cached in a CDN, which makes the content quickly available from wherever you are. The API provides content filtering options you can use to get just the content you need.

All requests to the API must be made securely over HTTPS with TLS 1.2.

You can use Delivery REST API either to retrieve published content or to preview content.

• Preview content – Get the latest versions of content items. The latest version can come from both published and unpublished content items.
• Published content – Get the published versions of content items.

In both cases, you use the same endpoints to request data but with a different base URL.

• To preview content from your project's environment, use:
  https://preview-deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/
• To retrieve published content from your project's environment, use:
  https://deliver.kontent.ai/<YOUR_ENVIRONMENT_ID>/

Get started with our tutorials on how to get content items, filter content items, and set up content preview.

Try the Kontent.ai APIs in Postman collection! Our Postman collection is regularly updated and contains endpoints for all Kontent.ai APIs.

We recommend that you fork the Kontent.ai APIs collection. Forking lets you stay up to date by pulling updates when needed.

Once you import the collection, you can start sending requests. Make sure to use environment variables for API keys.

Postman environments are sets of variables with specific values. You can use these variables everywhere in your requests in Postman.

For instance, the Kontent.ai APIs collection comes with an environment called Kontent.ai APIs sample values. The environment specifies a variable named environment_id, which is used in all requests. To get started quickly, we recommend you change the environment_id value to the ID of your own environment.

We offer the following SDKs to help you interact with Delivery API. However, you don't need an SDK to use the API.

• JavaScript/TypeScript SDK 
• .NET SDK
• Java SDK
• PHP SDK 
• Ruby SDK

If you want to create your own SDK, see our guidelines for SDK developers.

When you enable secure access for your environment or when you need to preview content, Delivery API requires an API key with each API request.

The API key expiration length is set to 1 year by default. This is also the recommended expiration length.

When creating or regenerating your API keys, you can specify your preferred API key expiration length. The expiration length can vary from 1 minute to 5 years.

Before the API key expires, we'll send email notifications to all Project managers in the project.

• If the expiration date is less than a day apart from the API key's creation date, the email notification is sent immediately.
• If the expiration date is between 1–7 days apart form the API key's creation date, the email notification is sent 1 day before the expiration date.
• If the expiration date is more than a week apart from the API key's creation date, the email notification is sent 1 week before the expiration date.

If you regenerate your API key before its expiration date, the API key is revoked after a few minutes, and you get a new API key. For requests made with a revoked API key, you receive the 403 Unauthorized error.

The API key isn't revoked if you deactivate secure access for your environment. Such API key remains valid and can be used again once secure access is activated for the environment.

The scope of the Delivery API keys depends on how the API keys are configured. The Delivery API keys can be limited to specific environments. For example, an API key can be restricted to the production environment.

The Delivery API keys are shared between all Project managers in the project.

Requests made to the Delivery API and Delivery Preview API count towards the overall API Calls limit set in the Fair Use Policy or your subscription plan. This includes requests for both published and unpublished content.

There is no limit on the total number of API calls you can make.

The Delivery API processes changes to your content items in sequential order, one after another. In high-volume scenarios, this can lead to delays between making a change and seeing the results of that change in the API. See the following example scenarios for details.

Example A: Editing and publishing content items

If you publish a content item, the API processes this change in a few seconds. When publishing larger amounts of content, there can be a delay in the availability of that content in the API.

For example, if you publish 100 content items, the first item will be available a few minutes sooner than the last one.

Example B: Editing content types

When you change a content type, the API needs to process all content items based on that type. If your changes affect hundreds or thousands of content items, the API recalculates the content of each item. While this is happening, any new changes to content items need to wait before being processed by the API.

For example, imagine you have an Article content type with 100,000 content items based on that type. If you add an element to the content type, the API processes the items and begins updating their content. Given the high number of items, this process can take up to a few hours.

Until the API finishes processing the Article items, any subsequent content changes need to wait. If you publish a content item right after modifying the Article content type, the published item appears in the API only after the type change was fully processed.

Example C: Changing localization settings

We strongly recommend against changing language codenames in production environments with lots of content. This action might lead to temporary inconsistencies that might affect the content in your web app.

If you change a language codename, the API needs to process all content items that have content in that language. Until the change is fully processed, the API might return some items with the old language codename and some items with the new language codename.

Rate limits specify the number of requests you can make to the Delivery API within a specific time window.

For cached requests served from our CDN, we don't enforce any rate limits. These are repeated requests for cached data.

For uncached requests that reach the Delivery API, we enforce a rate limitation of 100 requests per second and 2000 requests per minute. These are unique requests for uncached data.

When you reach the rate limit, 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.

When you request a single content item or list of items, the Delivery API limits the maximum number of items returned within a response to 2000 items. This number covers both the items that directly match the specified query and the linked items returned in the response's modular_content property.

You can find whether your requests are close to the limit by looking at the X-Request-Charge header.

If the X-Request-Charge value of your requests exceeds 1000, we recommend applying more specific filters and checking if a lower value for the depth parameter works for you. Fewer items returned per response means shorter response times and better performance for your app.

The Delivery API uses Fastly as its Content Delivery Network (CDN). The CDN stores responses to every successful API request in the CDN's cache.

Your first request to the Delivery API is uncached. It goes through the CDN directly to the Delivery API, and the response is then stored in the CDN. If you repeat the same request, you get a cached response from the CDN.

The response stays in the cache for as long as the requested content in your Kontent.ai environment stays the same. If the content changes, the cached response is removed from the cache.

For example, if you request a content item A from the API, you get an API response with the contents of content item A and its linked items. The API response with content item A is cached in the CDN. If you change content item A, the cached API response is removed from the cache. If the CDN had previously cached other responses containing content of content item A, these responses would have also been removed from the cache.

The 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 incorrect API key), and status codes in the 5xx range indicate an error on our side.

For troubleshooting failed requests, the API provides error messages defined in a consumable format to help you identify and fix the issue.

If you cannot identify and resolve an issue with your API call, you can contact us with the response status and the request ID you get in the error response.

You can specify which content items you want by using filtering parameters. You can filter by content in content elements and system properties. Filtering parameters don't apply to content items returned in the modular_content object property. Check out examples of filtering content items.

If you need to retrieve just a subset of elements, specify the elements you want using the elements filter. For example, elements=summary.

If you want to exclude a subset of elements while retrieving content items, you can specify those elements using the excludeElements filter. For example, items?excludeElements=location.

To filter by system property values, use a query parameter in the system.<property_name> format. The system properties are id, collection, name, codename, language, type, last_modified, workflow, and workflow_step. For example, to retrieve only content items based on the Article content type, use system.type=article as the query parameter.

To filter by content element values, you need to use a query parameter in the elements.<element_codename>=<value> format. For example, to retrieve only content items whose number element named Price has a value of 16, use elements.price=16 as a query parameter.

You can join multiple query parameters using the & character. Queries with two or more filtering parameters are more restrictive because the individual query parameters are merged with a logical conjunction (AND).

For example:

• The query system.type=article&elements.category[contains]=nature returns the Article content items tagged with the term Nature.
• The query elements.subpages[contains]=my_page returns the content items that link to the my_page content item in their subpages element. This means you get a list of items where the my_page item is used in.
• The query system.type=page&excludeElements=title will return Page content items without the element Title.

You can use the following filtering operators with both the system properties and element values.

You can use the [contains], [any], and [all] filtering operators only on arrays. The content elements that support these operators are custom elements (see limitations below), linked items, multiple choice, and taxonomy.

For custom elements, the [contains], [any], and [all] filters work only if the element's value is a stringified array of strings such as "[\"DE\",\"US\",\"UK\"]". The [contains], [any], and [all] operators can NOT be used on asset elements.

The [lt], [lte], [gt], [gte], and [range] filtering operators work best with numbers. For example, you can retrieve products with price larger or equal to 15 by using elements.price[gte]=15.

With Kontent.ai, you can compose and structure your content using rich text and linked items elements.

• Linked items elements are used to reference other content items.
• Rich text elements are used to compose your content with text, images, components, and content items. Components and content items are useful for inserting structured content into a specific point in the text.

• A component is a single-use content item.
• Just like content items, components are based on a specific content type.
• Unlike content items, components exist only within rich text elements.
• If a component and a content item are based on the same content type, they have the same structure. This applies both in the UI and API.

When retrieving items, the contents of all components and content items in the rich text and linked items elements are stored in the modular_content object property of the API response.

When enumerating the items, the modular_content object property contains only components.

The individual components and content items within the modular_content object property aren't ordered. See linked items and rich text elements for details on how ordering is done within the elements.

For historical reasons, the property is called "modular_content" instead of "linked_content".

Content items can reference other content items using linked items or rich text elements. These linked items can reference other items recursively. By default, the API returns only one level of linked items.

• To include more than one level of linked items in response, set the depth query parameter to 2 or more.
• To exclude all linked items, set the depth query parameter to 0.

When retrieving content, linked items cannot be filtered.

Components are not affected by the depth query parameter as they are an integral part of their rich text element. Components are always present in the API response. Components can be nested up to six levels deep.

When getting content items or content types, you get the elements object property as a part of the retrieved item or type.

Each element in elements contains the properties type, name, and value. Note that certain elements, such as rich text or taxonomy, can contain additional properties.

The Content type snippet elements are expanded into the elements that they contain. You can recognize the expanded elements by their codenames, which use the following format: <content_type_snippet_codename>__<content_element_codename>.

For example, when you retrieve an item that uses a snippet element with 2 elements, the snippet itself will be structured as the 2 elements, without any encapsulation.

"seo_metatata__meta_keywords": {
  "type": "text",
  "name": "Meta keywords",
  "value": "donation, africa"
},
"seo_metatata__meta_description": {
  "type": "text",
  "name": "Meta description",
  "value": "Regularly donate money."
}

Create your own custom elements or discover existing custom elements built by the community.

In addition to formatted text, the rich text element's value property can contain objects representing images, components, and content items.

Information about these objects is stored in separate properties:

• images – contains metadata about the assets used in the rich text.
• links – contains metadata about the content items linked in the rich text.
• modular_content – contains metadata about the linked items and components inserted in the rich text.

The rich text value can contain specific HTML elements, tags, and attributes, and must form a valid HTML5 fragment. Only the documented HTML attributes are supported. When transforming HTML to JSON, make sure to escape all double quotes.

The following HTML elements must be used at the top level in rich text content. They can also be used within a table cell <td>.

The following inline HTML elements can be used within the top-level elements and table cells.

The image assets in the rich text's value are represented by the figure and img HTML tags, along with the data-asset-id and data-image-id attributes, which contain the ID of the image asset.

<figure data-asset-id=\"66d73245-10e5-4478-93e7-5609fee3cdf7\"  data-image-id=\"66d73245-10e5-4478-93e7-5609fee3cdf7\"><img src=\"https://assets-us-01.kc-usercontent.com:443/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/66d73245-10e5-4478-93e7-5609fee3cdf7/image.jpg\" data-asset-id=\"66d73245-10e5-4478-93e7-5609fee3cdf7\" data-image-id=\"66d73245-10e5-4478-93e7-5609fee3cdf7\"alt=\"\"></figure>

The links in the rich text's value are represented by the a HTML tags.

<!-- Link to a content item -->
<a data-item-id=\"ef23e568-6aa2-42cd-a120-7823c0ef19f7\" href=\"\">link to a content item</a>

<!-- Link to a Web URL with title, set to open in a new window -->
<a href=\"https://example.com\" data-new-window=\"true\" title=\"Link title\" target=\"_blank\" rel=\"noopener noreferrer\">link to a Web URL that opens in a new window</a>

<!-- Link to a Web URL without title -->
<a href=\"https://example.com/\">link to a Web URL</a>

<!-- Link to an email address with a subject line -->
<a data-email-address=\"full.name@domain.com\" data-email-subject=\"Hello\" href=\"mailto:full.name@domain.com?subject=Hello\">contact me</a>

<!-- Link to a phone number -->
<a data-phone-number=\"+31-682144594\" href=\"tel:+31-682144594\">+31-682144594</a>

<!-- Link to an asset -->
<a data-asset-id=\"237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd\" href=\"https://assets-us-01.kc-usercontent.com:443/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/image.jpg\">link to asset</a>

The content items and components inserted in the rich text's value are represented by the object HTML element.

For both content items and components, the object HTML element specifies these attributes:

• data-type – Its value is item for both content items and components. This lets you use a single method to resolve your items and components.
• data-rel – Its value is either link (for content items inserted into rich text) or component (for components inserted into rich text). Use the attribute to differentiate between components and items.
• data-codename – Its value specifies the codename of the content item or component.

<!-- Inserted content item -->
<object type=\"application/kenticocloud\" data-type=\"item\" data-rel=\"link\" data-codename=\"content_item_codename\"></object>

<!-- Inserted component; the component's codename is system-generated -->
<object type="application/kenticocloud" data-type="item" data-rel="component" data-codename="n249afaaf_1de5_011f_f683_c78fd9ec9d7c"></object>

This element works only with Web Spotlight enabled.

Content items represent specific pieces of content based on a specific content type. By default, the API returns content items in the default language.

Content types define the structure of content items. Just like content items, each content type consists of specific content elements that define the data types for the content.