Delivery REST API (1)

Download OpenAPI specification:Download

Kontent.ai Support: support@kontent.ai License: MIT Terms of Service

About Delivery API

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.

Related paths

Published content vs. preview

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.

Protect your content

Your published content is public by default. To protect your published content, enable secure access for your environment.

Postman collection

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

Import the Postman collection

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.

Use environment variables

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.

SDKs

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

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

Authentication

BearerAuthentication

Delivery API doesn't require authentication by default. This means your assets and published content items are publicly available. If you enable secure access for Delivery API or want to preview content using Delivery Preview API, you need to authenticate your requests with a valid Delivery API key. You can also secure access to your assets.

To authenticate your Delivery API requests, send your requests over HTTPS and use the Authorization header in the following format: Authorization: Bearer <YOUR_API_KEY>. To create and manage your API keys, go to Kontent.ai > Project settings > API keys. Requests with an incorrect or missing Authorization header will fail with an error.

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "<YOUR_DELIVERY_API_KEY>"

API keys

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.

Expiration

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.

Email reminders before expiration

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.

Revocation

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.

Scope

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.

API limitations

API requests limit

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.

Change processing time

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 limitation

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.

Response size

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.

How the API caches your content

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. This request goes through the CDN directly to the Delivery API. The response from the Delivery API 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 make changes to 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 are also removed from the cache.

Errors

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.

HTTP status codes summary

Status code Description
400 Bad Request The request was not understood. Check if your request is missing a required parameter or contains an invalid query parameter value.
401 Unauthorized The provided API key is doesn't provide access to the requested resource. The error can also occur if the API key is malformed or missing. Try copying and pasting your current API key to avoid typos.
403 Forbidden The provided API key is valid but doesn't provide permission for the specified resource.
404 Not Found The requested resource doesn't exist. Try checking the resource name for typos.
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. Try your request again after a few seconds as specified 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.

Resolving errors

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

Error object in Delivery API.

message
required
string

The error message explaining what caused the error.

request_id
string or null

The performed request's unique ID.

error_code
integer <int32> [ 1 .. 500 ]

The internal error code for the type of error. Used for finding patterns among error requests.

specific_code
integer <int32>

Only useful for finding reasons behind failed requests in specific cases.

{
  • "message": "The continuation token specified in the 'X-Continuation' request header is malformed.",
  • "request_id": "d9b4b4e4750ee210",
  • "error_code": 107,
  • "specific_code": 0
}

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.

Filtering parameters

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.

Filter by system values

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.

Filter by element values

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.

Join multiple query parameters

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 will return Article content items tagged with the term Nature.
  • The query /items-feed?system.type=page&excludeElements=title will return Page content items without the element Title.

Filtering operators

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

All operators are case-sensitive.

Operator Description Example Use with
[eq] (same as =) Property value equals the specified value. system.type=article system.type[eq]=article Simple types
[neq] Property value does not equal the specified value. system.type[neq]=article system.workflow_step[neq]=archived Simple types
[empty] Property value is empty. elements.title[empty] elements.author[empty] For rich text, use the equals operator, elements.content[eq]=<p><br></p>. Simple types and arrays
[nempty] Property value is not empty. elements.title[nempty] Simple types and arrays
[lt] Property value is less than the specified value. See Comparing values. system.last_modified[lt]=2019-03-01 elements.price[lt]=10 Simple types
[lte] Property value is less than or equal to the specified value. See Comparing values. system.last_modified[lt]=2019-02-01 elements.price[lte]=4 Simple types
[gt] Property value is greater than the specified value. See Comparing values. system.last_modified[gt]=2019-01-01 elements.price[gt]=10 Simple types
[gte] Property value is greater than or equal to the specified value. See Comparing values. system.last_modified[gte]=2019-02-28 elements.price[gt]=10 Simple types
[range] Property value falls within the specified range of two values, both inclusive. See Comparing values. system.last_modified[range]=2018-02-01,2018-03-31 elements.price[range]=10.5,50 Simple types
[in] Property value is in the specified list of values. system.type[in]=cafe,coffee elements.price[in]=8.5,9,10.5 Simple types
[nin] Property value is not in the specified list of values. system.type[nin]=home,page Simple types
[contains] Property with an array of values contains the specified value.The [contains] operator cannot be used on strings. elements.category[contains]=nature elements.custom[contains]=ABC Arrays
[any] Property with an array of values contains at least one value from the specified list of values. elements.category[any]=technology,nature Arrays
[all] Property with an array of values contains all of the specified values. elements.category[all]=technology,mobile Arrays

Arrays vs. simple types

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.

Comparing values

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.

Filtering by date-time values

Properties that store dates are represented as strings. For example, this includes the last_modified system property and date & time content elements.

If you use filtering operators on properties with string values, the Delivery API tries to perform a string comparison. For instance, you can retrieve content items modified during February and March by using a query such as system.last_modified[range]=2020-02-01,2020-04-01, specifying the start date within the range and end date outside the range.

Linked content and components

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.

Components in Kontent.ai

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

Retrieve linked content

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

Linked content depth

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.

Content elements

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.

Asset element

type
required
string

The element's type.

Allowed value Description
asset

Specifies the asset element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

required
Array of objects

The assets inserted into the element. The asset objects are returned in the same order as shown in the UI.

Some of the properties are specific to images only: width and height represent the image’s width and height dimensions, and the renditions object contains details about 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.

{}

Content type snippet element

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

Custom element

type
required
string

The element's type.

Allowed value Description
custom

Specifies the custom element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

value
required
string or null [ 1 .. 100000 ] characters

The element's value.

{
  • "type": "custom",
  • "name": "Markdown editor",
  • "value": "# Heading\n\nPlaintext\n\n[link](https://example.com)"
}

Date and time element

type
required
string

The element's type.

Allowed value Description
date_time

Specifies the date & time element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

value
required
string or null <date-time>

The element's value as a ISO-8601 formatted string. Time in this element is displayed and interpreted as UTC.

display_timezone
string or null

IANA time zone name used to display time offset of the date & time element in the UI.

The time zone doesn't modify the date specified in the value property.

Obsolete values: "America/Ojinaga", "Asia/Qyzylorda", "Europe/Kiev".

Allowed values: "Africa/Abidjan" "Africa/Accra" "Africa/Addis_Ababa" … 319 more
{
  • "type": "date_time",
  • "name": "Post date",
  • "value": "2019-08-26T13:56:37.7643832Z",
  • "display_timezone": "Europe/London"
}

Linked items element

type
required
string

The element's type.

Allowed value Description
modular_content

Specifies the linked items element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

value
required
Array of strings unique

The linked content items as an array of item codenames.

Matching order

The order of the codenames in the array matches the order of the content items in the UI. The content of these items can be found in the modular_content property (where the items are not ordered) of the API response when getting content items.

{
  • "type": "modular_content",
  • "name": "Author",
  • "value": [
    • "author_item_codename"
    ]
}

Multiple choice element

type
required
string

The element's type.

Allowed value Description
multiple_choice

Specifies the multiple choice element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

required
Array of objects unique

The element's value as an array of selected multiple choice options.

Matching order

The order of the objects in the array matches the order of the options in the UI.

{
  • "type": "multiple_choice",
  • "name": "The Earth is flat",
  • "value": [
    • {
      • "name": "False",
      • "codename": "false"
      }
    ]
}

Number element

type
required
string

The element's type.

Allowed value Description
number

Specifies the number element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

value
required
number or null <float>

The element's value.

{
  • "type": "number",
  • "name": "Days since last accident",
  • "value": 7
}

Rich text element

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.
type
required
string

The element's type.

name
required
string [ 1 .. 50 ] characters

The element's display name.

required
object

The images inserted into the rich text element. Each image object contains the image's metadata.

required
object

The hyperlinks in the text that point to content items. Each link object contains the linked item's metadata.

modular_content
required
Array of strings unique

Contains codenames of the components and content items (not their contents) inserted into the rich text element.

To get the contents of the inserted components and items, see how to retrieve linked content.

Two distinct modular_content properties

  • The Delivery API responses for getting items contain the modular_content object property. In this property, you'll find the contents of the linked content items and content components.
  • Rich text element objects contain the modular_content array property. In this property, you'll find only the codenames of the inserted content items and content components. These codenames are grouped and ordered. First comes a group of content item codenames followed by a group of component codenames. The order of codenames in each group matches that in the UI.
value
required
string <= 100000 characters

The element's value. If the rich text element doesn't contain any content, its value defaults to a single empty paragraph: <p><br></p>.

Nesting HTML elements in rich text

At the top level, only the following elements are allowed: <p>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <ul>, <ol>, <table>, <object> (for content items and components), and <figure> (for images). These top-level elements can NOT be nested except for lists (<ul> and <ol>). Text is not allowed at the top level with the exception of new lines and white space characters.

The table <td> element can alternatively contain top level elements except for <table> and <object>.

The <p>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <li>, and <td> elements can contain text and the following inline elements: <a>, <code>, <em>, <strong>, <sub>, <sup>. These elements can also contain <br/> elements for specifying line breaks.

The <a>, <code>, <em>, and <strong> inline elements can be nested but they cannot cross one another. For example, it's not allowed to open the <em> element, then the <strong> element, and then close the <em> element. Lists can be nested as long as the nested list (<ul> or <ol>) is the last HTML element of the list item, for example, <ol><li>List item<ul><li>Nested list item</li></ul></li></ol>.

{
  • "type": "rich_text",
  • "name": "Rich text showcase",
  • "images": {},
  • "links": {
    • "ef23e568-6aa2-42cd-a120-7823c0ef19f7": {
      • "codename": "content_item_codename",
      • "type": "article",
      • "url_slug": "my-article"
      }
    },
  • "modular_content": [
    • "content_item_codename",
    • "n26275539_7e71_01ce_ee08_e55340bb9ea6"
    ],
  • "value": "<p>Basic formatted text: plain text, <strong>bold</strong>, <em>italics</em>, <code>monospace</code>, <sub>subscript</sub>, <sup>superscript</sup>.</p>\n<p>Links: <a data-item-id=\\\"ef23e568-6aa2-42cd-a120-7823c0ef19f7\\\" href=\\\"\\\">link to a content item</a>, <a href=\\\"https://kontent.ai/\\\" data-new-window=\\\"true\\\" target=\\\"_blank\\\" rel=\\\"noopener noreferrer\\\">link to web URL</a>, <a data-email-address=\\\"sales@kontent.ai\\\" href=\\\"mailto:sales@kontent.ai\\\">email link</a>, <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>.</p>\n<p>Table</p>\n<table><tbody>\n <tr><td>A</td><td>B</td><td>C</td></tr>\n <tr><td>D</td><td>E</td><td>F</td></tr>\n <tr><td>G</td><td>H</td><td>I</td></tr>\n</tbody></table>\n<p>Image</p>\n<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>\n<p>Inserted content item</p>\n<object type=\\\"application/kenticocloud\\\" data-type=\\\"item\\\" data-rel=\\\"link\\\" data-codename=\\\"content_item_codename\\\"></object>\n<p>Component</p>\n<object type=\\\"application/kenticocloud\\\" data-type=\\\"item\\\" data-rel=\\\"component\\\" data-codename=\\\"n26275539_7e71_01ce_ee08_e55340bb9ea6\\\"></object>"
}

HTML5 elements allowed in 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.

Top-level elements

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

Types HTML elements Notes
Paragraphs <p>...</p> Can contain text with inline formatting elements.
Headings <h1>...</h1>, <h2>...</h2>, <h3>...</h3>, <h4>...</h4>, <h5>...</h5>, <h6>...</h6> Can contain text with inline formatting elements.
Lists <ol><li>...</li></ol>, <ul><li>...</li></ul> Individual list items <li> can contain text with inline formatting elements.
Assets <figure ...><img ...></figure>
Tables <table><tbody><tr><td>...</td></tr></tbody></table> The <thead> and <tfoot> tags are not supported. Individual table cells <td> can contain either text with inline formatting elements, or top-level elements. Nested tables are not supported inside table cells.
Content items and components <object ...></object> Content items and components are not supported inside table cells.

Elements for inline text formatting

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

Types HTML elements Notes
Bold text <strong>...</strong> The <b> tag is not supported.
Italic text <em>...</em> The <i> tag is not supported.
Superscript <sup>...</sup> Superscript and subscript are mutually exclusive.
Subscript <sub>...</sub> Superscript and subscript are mutually exclusive.
Code <code>...</code>
Links <a ...>...</a> For the list of supported <a> attributes, see Links in rich text.
Line breaks <br/>

Images in rich text

The name of the object represents an image id such as 14mio.

image_id
required
string <uuid>

The image's ID.

description
required
string

The image's description in a specific language. Used for the alt attribute of an <img> tag.

url
required
string

The image's absolute URL.

width
required
integer <int32>

The image's width.

height
required
integer <int32>

The image's height.

{}

The images in the rich text's value are represented by the figure and img HTML tags.

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

Content items and components in rich text

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>

Subpages element

This element works only with Web Spotlight enabled.

type
required
string

The element's type.

Allowed value Description
modular_content

Specifies the subpages element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

value
required
Array of strings unique

The linked pages as an array of item codenames.

Matching order

The order of the codenames in the array matches the order of the content items in the UI. The content of these items can be found in the modular_content property (where the items are not ordered) of the API response when getting content items.

{
  • "type": "modular_content",
  • "name": "Subpages",
  • "value": [
    • "about_us",
    • "contact"
    ]
}

Taxonomy element

type
required
string

The element's type.

Allowed value Description
taxonomy

Specifies the taxonomy element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

taxonomy_group
required
string

The codename of a specific taxonomy group that the element is using.

required
Array of objects

The element's value as an array of selected taxonomy terms.

{
  • "type": "taxonomy",
  • "name": "Categories",
  • "taxonomy_group": "categories",
  • "value": [
    • {
      • "name": "Technology",
      • "codename": "technology"
      }
    ]
}

Text element

type
required
string

The element's type.

Allowed value Description
text

Specifies the text element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

value
required
string or null <= 100000 characters

The element's value.

{
  • "type": "text",
  • "name": "Meta keywords",
  • "value": "donation, charity"
}

URL slug element

type
required
string

The element's type.

Allowed value Description
url_slug

Specifies the URL slug element.

name
required
string [ 1 .. 50 ] characters

The element's display name.

value
required
string

The element's value can be either auto-generated from a text element or custom.

{
  • "type": "url_slug",
  • "name": "URL",
  • "value": "structure-your-content"
}

Content items

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 item object

The content item with metadata and individual elements.

required
object

The content item's system properties.

required
object

The item's elements with values for the specific language. The order of the element objects might not match the content element order in the UI.

{
  • "system": {
    • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
    • "collection": "default",
    • "name": "My article",
    • "codename": "my_article",
    • "language": "en-US",
    • "type": "article",
    • "sitemap_locations": [ ],
    • "last_modified": "2019-03-27T13:21:11.38Z",
    • "workflow": "default",
    • "workflow_step": "published"
    },
  • "elements": {
    • "author": {
      • "type": "modular_content",
      • "name": "Author",
      • "value": [
        • "jenny_brown"
        ]
      },
    • "url": {
      • "type": "url_slug",
      • "name": "URL pattern",
      • "value": "writing-good-error-messages"
      }
    }
}

List content items

get/{environment_id}/items

Retrieve a list of content items from the specified environment. By default, the API returns an unfiltered paginated list of content items in the default language ordered alphabetically by codename. The response size is limited to 2000 items.

The modular_content object property will contain both components and linked items in the API response. See Linked content and components for more details.

If you need to export all content items, we recommend you enumerate content items.

Get only the items you need

To retrieve specific content items, use the filtering parameters in your requests. For example, you can request items tagged with a taxonomy term, items of a specific type, or items modified in the past three days.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
query Parameters
language
string

Determines which language variant of content items to return. By default, the API returns content in the default language.

If the requested content is not available in the specified language variant, the API follows the language fallbacks as configured in the Localization settings.

Example: language=en-US
elements
string

Determines which content elements to retrieve. The elements are specified as a comma-separated list of element codenames. By default, all elements are retrieved.

Examples

  • Retrieve a single element – elements=title
  • Retrieve multiple elements – elements=title,summary,related_articles

Usage notes

  • The filter applies to all content items within the response. That is both the items array and modular_content object property.
  • If the specified elements don't match the elements present in the content items, the API returns the content items without any elements.
  • The filter doesn't apply to content components. For example, if you retrieve only rich text elements, you need complete components used in the rich text to construct the rich text content.
Example: elements=title,summary
excludeElements
string

Determines which content elements to exclude. The elements are specified as a comma-separated list of element codenames. By default, all elements are retrieved.

Examples

  • Exclude a single element – excludeElements=title
  • Exclude multiple elements – excludeElements=title,summary,related_articles

Usage notes

  • The filter applies to all content items within the response. That is both the items array and modular_content object property.
  • If the specified elements don't match the elements present in the content items, the API response returns all elements of the content items without any exclusion.
  • The filter doesn't apply to content components. For example, if you retrieve only rich text elements, you need complete components used in the rich text to construct the rich text content.
Example: excludeElements=title,summary
order
string

Determines the order of the retrieved objects. By default, the objects are sorted alphabetically by their codenames from A to Z in descending order.

To sort the requested objects in ascending order, set the order to <property_name>[asc] where <property_name> is the name of the object property you want to sort by. For example, order=elements.title[asc] or order=system.codename[asc]. Similarly, to sort in descending order, use the [desc] modifier. You can sort by any properties in the API response.

Examples

  • Sort by date – order=system.last_modified[desc]
  • Sort by a content item name – order=system.name[asc]
  • Sort by an element value – order=elements.<element_codename>[asc]
Example: order=system.last_modified[desc]
depth
integer <int32> >= 0

Determines the nesting level for linked content items that the API returns. By default, only the first level of linked items is returned, which is the same as setting depth=1.

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

Components are always present in response. See Linked content and components for more details.

Example: depth=1
skip
integer <int32> >= 0

Sets the number of objects to skip when requesting a list of objects. The skip parameter must be combined with the limit parameter to work. If skip is not specified, the API returns the first page of results.

You can combine the limit and skip parameters to specify page size and page number. For example, using limit=10&skip=10 sets the page size to 10 and gets the second page of results.

Example: skip=10
limit
integer <int32> >= 0

Sets the number of objects to retrieve in a single request. If the limit parameter is not specified, the API returns all requested objects by default.

If limit is lower than the total number of objects matching your query, the next_page property in the pagination object of the API response will contain a URL to the next page of results.

The limit parameter affects only the number of items in the items property. It doesn't reduce the number of linked items in the modular_content property so you may hit the response size limit unexpectedly. You can set depth=0 to avoid that.

Example: limit=10
includeTotalCount
boolean

Adds the information about the total number of content items matching your query. Only the content filtering parameters affect the resulting number. Other parameters in your query, such as limit, skip, or order, don't have an effect on it.

The number doesn't include linked items returned as part of the modular_content property. For the total number of items returned within the response, see the X-Request-Charge header.

When set to true, the pagination object returned in the API response contains an additional total_count property.

Example: includeTotalCount=false
header Parameters
X-KC-Wait-For-Loading-New-Content
boolean

Determines whether the API waits while fetching latest content. By default, the header is not set and the API serves stale content (if cached by the CDN) while fetching the new content to minimize wait time.

The header can be useful if you know that the requested content had changed since your last request in a reaction to a webhook notification.

Example: false
Responses
200

A paginated list of content items matching the specified criteria.

400

Maximum response size reached.

Request samples
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("<YOUR_ENVIRONMENT_ID>");

// Registers the model class for articles
// Tip: Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models
client.registerType(Article.class);

// Gets 3 articles ordered by the "Post date" element
CompletionStage<List<Article>> articles = client.getItems(
    Article.class,
    DeliveryParameterBuilder.params()
        .page(null, 3)
        .orderByDesc("post_date")
        .build()
);
Response samples
application/json
{
  • "items": [
    • {
      • "system": {
        • "id": "4d4dc14d-8c7c-471f-b797-c6694c604964",
        • "name": "About us",
        • "codename": "about_us",
        • "language": "en-US",
        • "type": "article",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-17T07:22:51.6711216Z",
        • "workflow": "default",
        • "workflow_step": "published"
        },
      • "elements": {
        • "title": {
          },
        • "body_copy": {
          },
        • "related_articles": {
          },
        • "author": {
          },
        • "url": {
          }
        }
      },
    • {
      • "system": {
        • "id": "0afdd600-d6c5-4ac4-bb6b-d2847ca779fe",
        • "name": "About us",
        • "codename": "about_us_0afdd60",
        • "language": "en-US",
        • "type": "navigation_item",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-04T15:14:48.0057835Z",
        • "workflow": "default",
        • "workflow_step": "published"
        },
      • "elements": {
        • "title": {
          },
        • "url": {
          },
        • "subitems": {
          }
        }
      }
    ],
  • "modular_content": {
    • "about_us": {
      • "system": {
        • "id": "4d4dc14d-8c7c-471f-b797-c6694c604964",
        • "name": "About us",
        • "codename": "about_us",
        • "language": "en-US",
        • "type": "article",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-17T07:22:51.6711216Z",
        • "workflow": "default",
        • "workflow_step": "published"
        },
      • "elements": {
        • "title": {
          },
        • "body_copy": {
          },
        • "related_articles": {
          },
        • "author": {
          },
        • "url": {
          }
        }
      },
    • "jenny_brown": {
      • "system": {
        • "id": "59838cfd-ba15-4607-8e6a-d91931fc7ce6",
        • "name": "Jenny Brown",
        • "codename": "jenny_brown",
        • "language": "en-US",
        • "type": "author",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-05T11:33:54.5271987Z",
        • "workflow": "default",
        • "workflow_step": "published"
        },
      • "elements": {
        • "name": {
          },
        • "bio": {
          }
        }
      },
    • "my_article": {
      • "system": {
        • "id": "29b82988-fb9e-4327-a34b-b568cfaa39e9",
        • "name": "My article",
        • "codename": "my_article",
        • "language": "en-US",
        • "type": "article",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-03T13:58:21.5779868Z",
        • "workflow": "default",
        • "workflow_step": "published"
        },
      • "elements": {
        • "title": {
          },
        • "body_copy": {
          },
        • "related_articles": {
          },
        • "author": {
          },
        • "url": {
          }
        }
      },
    • "n43768251_0eaa_01f6_69c2_f93047f076e1": {
      • "system": {
        • "id": "43768251-0eaa-01f6-69c2-f93047f076e1",
        • "name": "43768251-0eaa-01f6-69c2-f93047f076e1",
        • "codename": "n43768251_0eaa_01f6_69c2_f93047f076e1",
        • "language": "en-US",
        • "type": "tweet",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-17T07:22:51.6711216Z"
        },
      • "elements": {
        • "theme": {
          },
        • "tweet_link": {},
        • "display_options": {
          }
        }
      }
    },
  • "pagination": {}
}

Retrieve a content item

get/{environment_id}/items/{item_codename}

Retrieve a content item by its codename.

The response size is limited to 2000 items.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_codename
required
string

Identifies the content item by codename.

Example: on_roasts
query Parameters
language
string

Determines which language variant of content items to return. By default, the API returns content in the default language.

If the requested content is not available in the specified language variant, the API follows the language fallbacks as configured in the Localization settings.

Example: language=en-US
elements
string

Determines which content elements to retrieve. The elements are specified as a comma-separated list of element codenames. By default, all elements are retrieved.

Examples

  • Retrieve a single element – elements=title
  • Retrieve multiple elements – elements=title,summary,related_articles

Usage notes

  • The filter applies to all content items within the response. That is both the items array and modular_content object property.
  • If the specified elements don't match the elements present in the content items, the API returns the content items without any elements.
  • The filter doesn't apply to content components. For example, if you retrieve only rich text elements, you need complete components used in the rich text to construct the rich text content.
Example: elements=title,summary
excludeElements
string

Determines which content elements to exclude. The elements are specified as a comma-separated list of element codenames. By default, all elements are retrieved.

Examples

  • Exclude a single element – excludeElements=title
  • Exclude multiple elements – excludeElements=title,summary,related_articles

Usage notes

  • The filter applies to all content items within the response. That is both the items array and modular_content object property.
  • If the specified elements don't match the elements present in the content items, the API response returns all elements of the content items without any exclusion.
  • The filter doesn't apply to content components. For example, if you retrieve only rich text elements, you need complete components used in the rich text to construct the rich text content.
Example: excludeElements=title,summary
depth
integer <int32> >= 0

Determines the nesting level for linked content items that the API returns. By default, only the first level of linked items is returned, which is the same as setting depth=1.

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

Components are always present in response. See Linked content and components for more details.

Example: depth=1
header Parameters
X-KC-Wait-For-Loading-New-Content
boolean

Determines whether the API waits while fetching latest content. By default, the header is not set and the API serves stale content (if cached by the CDN) while fetching the new content to minimize wait time.

The header can be useful if you know that the requested content had changed since your last request in a reaction to a webhook notification.

Example: false
Responses
200

A single content item object.

404

The specified content item is not published or was deleted.

Request samples
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("<YOUR_ENVIRONMENT_ID>");

// Registers the model class for articles
// Tip: Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models
client.registerType(Article.class);

// Gets an article
CompletionStage<Article> article = client.getItem("my_article", Article.class);
Response samples
application/json
{
  • "item": {
    • "system": {
      • "id": "7b11fe14-6282-4daa-b901-e59e231cd93c",
      • "name": "How to write error messages",
      • "codename": "how_to_error_message",
      • "language": "en-US",
      • "type": "article",
      • "collection": "default",
      • "sitemap_locations": [ ],
      • "last_modified": "2020-12-16T15:08:53.2391808Z",
      • "workflow": "default",
      • "workflow_step": "published"
      },
    • "elements": {
      • "title": {
        • "type": "text",
        • "name": "Title",
        • "value": "Writing good error messages"
        },
      • "body_copy": {
        • "type": "rich_text",
        • "name": "Body",
        • "images": { },
        • "links": { },
        • "modular_content": [
          ],
        • "value": "<p>The 3 most important things when writing error messages</p>\n<ol>\n <li>Don’t abuse alerts for upselling or showing superfluous information. People will stop reading the messages that are actually important.</li>\n <li>Don’t just assume people know about the context of a message. They might toggle between apps and see your message days after it happened. Always include enough information for users to make sense of it.</li>\n <li>Use a friendly, non-technical, non-threatening tone of voice.</li>\n</ol>\n<p><em><strong>TL;DR Write actionable error messages that laypeople can understand.*</strong></em></p>\n<p><em>*Not sure if they do? Show them to a non-technical person and ask them to explain it back to you.</em></p>\n<p><em>Read the full story on </em><a href=\"https://medium.com/@thomasfuchs/how-to-write-an-error-message-883718173322\" data-new-window=\"true\" title=\"How to write a great error message\" target=\"_blank\" rel=\"noopener noreferrer\"><em>Medium</em></a><em>.</em></p>\n<object type=\"application/kenticocloud\" data-type=\"item\" data-rel=\"component\" data-codename=\"n78ee300e_7a58_0117_819e_529b2294067b\"></object>"
        },
      • "author": {
        • "type": "modular_content",
        • "name": "Author",
        • "value": [
          ]
        },
      • "url": {
        • "type": "url_slug",
        • "name": "URL pattern",
        • "value": "writing-good-error-messages"
        }
      }
    },
  • "modular_content": {
    • "jenny_brown": {
      • "system": {
        • "id": "59838cfd-ba15-4607-8e6a-d91931fc7ce6",
        • "name": "Jenny Brown",
        • "codename": "jenny_brown",
        • "language": "en-US",
        • "type": "author",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-05T11:33:54.5271987Z",
        • "collection": "default",
        • "workflow": "default",
        • "workflow_step": "published"
        },
      • "elements": {
        • "name": {
          },
        • "bio": {
          }
        }
      },
    • "n78ee300e_7a58_0117_819e_529b2294067b": {
      • "system": {
        • "id": "78ee300e-7a58-0117-819e-529b2294067b",
        • "name": "78ee300e-7a58-0117-819e-529b2294067b",
        • "codename": "n78ee300e_7a58_0117_819e_529b2294067b",
        • "language": "en-US",
        • "type": "blockquote",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-12-16T15:08:53.2391808Z"
        },
      • "elements": {
        • "quote": {
          },
        • "source": {
          }
        }
      }
    }
}

Enumerate content items

get/{environment_id}/items-feed

Retrieve a dynamically paginated list of content items ordered alphabetically by codename.

If the response comes with the X-Continuation header, it means that there are more pages to retrieve. To get the next page of results, send the X-Continuation header with your request as you received it.

We recommend using this endpoint for warming up your app's cache (that is getting all content into the cache after the app starts) or for exporting the content of your project's environment.

This endpoint, unlike the List content items endpoint, guarantees to enumerate all content items in the specified environment. The modular_content object property will contain only components used in rich text elements in the API response. See Linked content and components for more details.

Get only the items you need

To retrieve specific content items, use the filtering parameters in your requests. For example, you can request items tagged with a taxonomy term, items of a specific type, or items modified in the past three days.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
query Parameters
language
string

Determines which language variant of content items to return. By default, the API returns content in the default language.

If the requested content is not available in the specified language variant, the API follows the language fallbacks as configured in the Localization settings.

Example: language=en-US
elements
string

Determines which content elements to retrieve. The elements are specified as a comma-separated list of element codenames. By default, all elements are retrieved.

Examples

  • Retrieve a single element – elements=title
  • Retrieve multiple elements – elements=title,summary,related_articles

Usage notes

  • The filter applies to all content items within the response. That is both the items array and modular_content object property.
  • If the specified elements don't match the elements present in the content items, the API returns the content items without any elements.
  • The filter doesn't apply to content components. For example, if you retrieve only rich text elements, you need complete components used in the rich text to construct the rich text content.
Example: elements=title,summary
excludeElements
string

Determines which content elements to exclude. The elements are specified as a comma-separated list of element codenames. By default, all elements are retrieved.

Examples

  • Exclude a single element – excludeElements=title
  • Exclude multiple elements – excludeElements=title,summary,related_articles

Usage notes

  • The filter applies to all content items within the response. That is both the items array and modular_content object property.
  • If the specified elements don't match the elements present in the content items, the API response returns all elements of the content items without any exclusion.
  • The filter doesn't apply to content components. For example, if you retrieve only rich text elements, you need complete components used in the rich text to construct the rich text content.
Example: excludeElements=title,summary
order
string

Determines the order of the retrieved objects. By default, the objects are sorted alphabetically by their codenames from A to Z in descending order.

To sort the requested objects in ascending order, set the order to <property_name>[asc] where <property_name> is the name of the object property you want to sort by. For example, order=elements.title[asc] or order=system.codename[asc]. Similarly, to sort in descending order, use the [desc] modifier. You can sort by any properties in the API response.

Examples

  • Sort by date – order=system.last_modified[desc]
  • Sort by a content item name – order=system.name[asc]
  • Sort by an element value – order=elements.<element_codename>[asc]
Example: order=system.last_modified[desc]
header Parameters
X-KC-Wait-For-Loading-New-Content
boolean

Determines whether the API waits while fetching latest content. By default, the header is not set and the API serves stale content (if cached by the CDN) while fetching the new content to minimize wait time.

The header can be useful if you know that the requested content had changed since your last request in a reaction to a webhook notification.

Example: false
X-Continuation
string

Determines the next page of results to retrieve. By default, when the header is not set, the API returns the first page of results.

If there are more items to enumerate, the response will come with the X-Continuation header. To get the next page of results, use the X-Continuation header from the response in your request.

Example: eyJwcm9qZWN0X2lkIjoiNGE4YjQ0ZmEtNzg1Yy0wMGFlLTRkNWMtMDI5ZGU3NDI4Y2FiIiwidGltZXN0YW1wIjoiMjAyMi0xMC0yMFQwOTo1MzozMC4wMTA3MjAxWiIsImZpbHRlciI6IiIsInZlcnNpb24iOiIxLjAifQ==
Responses
200

A dynamically paginated feed of content items and components.

Request samples
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
const KontentDelivery = require('@kontent-ai/delivery-sdk');

const client = KontentDelivery.createDeliveryClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>'
});

// Gets feed of all articles in the project
const response = await client.itemsFeed()
  .type('article')
  .toAllPromise();
Response samples
application/json
{
  • "items": [
    • {
      • "system": {
        • "id": "4d4dc14d-8c7c-471f-b797-c6694c604964",
        • "name": "About us",
        • "codename": "about_us",
        • "language": "en-US",
        • "type": "article",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-17T07:22:51.6711216Z",
        • "workflow": "default",
        • "workflow_step": "published"
        },
      • "elements": {
        • "title": {
          },
        • "body_copy": {
          },
        • "author": {
          },
        • "url": {
          }
        }
      },
    • {
      • "system": {
        • "id": "7b11fe14-6282-4daa-b901-e59e231cd93c",
        • "name": "How to write error messages",
        • "codename": "how_to_error_message",
        • "language": "en-US",
        • "type": "article",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-12-16T15:08:53.2391808Z",
        • "workflow": "default",
        • "workflow_step": "published"
        },
      • "elements": {
        • "title": {
          },
        • "body_copy": {
          },
        • "author": {
          },
        • "url": {
          }
        }
      },
    • {
      • "system": {
        • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
        • "name": "Simple article",
        • "codename": "simple_article",
        • "language": "en-US",
        • "type": "simple_article",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-06T10:08:58.1048397Z",
        • "workflow": "default",
        • "workflow_step": "published"
        },
      • "elements": {
        • "title": {
          },
        • "author": {
          },
        • "body": {
          }
        }
      }
    ],
  • "modular_content": {
    • "n43768251_0eaa_01f6_69c2_f93047f076e1": {
      • "system": {
        • "id": "43768251-0eaa-01f6-69c2-f93047f076e1",
        • "name": "43768251-0eaa-01f6-69c2-f93047f076e1",
        • "codename": "n43768251_0eaa_01f6_69c2_f93047f076e1",
        • "language": "en-US",
        • "type": "tweet",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-17T07:22:51.6711216Z"
        },
      • "elements": {
        • "theme": {
          },
        • "tweet_link": {},
        • "display_options": {
          }
        }
      },
    • "n499599bf_6bda_019e_d2f7_debd4589f3b8": {
      • "system": {
        • "id": "499599bf-6bda-019e-d2f7-debd4589f3b8",
        • "name": "499599bf-6bda-019e-d2f7-debd4589f3b8",
        • "codename": "n499599bf_6bda_019e_d2f7_debd4589f3b8",
        • "language": "en-US",
        • "type": "code_sample",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-02-06T10:08:58.1048397Z"
        },
      • "elements": {
        • "code": {
          },
        • "programming_language": {
          }
        }
      },
    • "n78ee300e_7a58_0117_819e_529b2294067b": {
      • "system": {
        • "id": "78ee300e-7a58-0117-819e-529b2294067b",
        • "name": "78ee300e-7a58-0117-819e-529b2294067b",
        • "codename": "n78ee300e_7a58_0117_819e_529b2294067b",
        • "language": "en-US",
        • "type": "blockquote",
        • "collection": "default",
        • "sitemap_locations": [ ],
        • "last_modified": "2020-12-16T15:08:53.2391808Z"
        },
      • "elements": {
        • "quote": {
          },
        • "source": {
          }
        }
      }
    }
}

Content types

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.

Content type object

required
object

The content type's system properties.

required
object

A list of elements that define the content type.

Order may not match the order in UI

The order of the elements in the API response might not match their order in the UI.

{
  • "system": {
    • "id": "b2c14f2c-6467-460b-a70b-bca17972a33a",
    • "name": "Article",
    • "codename": "article",
    • "last_modified": "2019-10-20T12:03:17.4685693Z"
    },
  • "elements": {
    • "multiple_choice": {
      • "type": "multiple_choice",
      • "name": "Multiple choices",
      • "options": [
        • {
          },
        • {
          }
        ]
      },
    • "text": {
      • "type": "text",
      • "name": "Text element"
      },
    • "taxonomy": {
      • "type": "taxonomy",
      • "name": "Categories taxonomy",
      • "taxonomy_group": "categories"
      }
    }
}

List content types

get/{environment_id}/types

Retrieve a paginated list of content types. By default, the API returns all content types ordered alphabetically by codename.

You can customize pagination by specifying both the skip and limit query parameters.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
query Parameters
elements
string

Determines a subset of the content type's elements to retrieve. The elements are specified using a comma-separated list of element codenames. By default, all elements are retrieved.

Examples

  • Retrieve a single element – elements=title
  • Retrieve multiple elements – elements=title,summary,related_articles

If the specified elements don't match the elements present in the content type, the API returns the content type without any elements.

The elements filter applies to all content types within the types array. The filter doesn't apply to the content types' system properties. This means you cannot omit the system object from the response.

Example: elements=title,summary
skip
integer <int32> >= 0

Sets the number of objects to skip when requesting a list of objects. The skip parameter must be combined with the limit parameter to work. If skip is not specified, the API returns the first page of results.

You can combine the limit and skip parameters to specify page size and page number. For example, using limit=10&skip=10 sets the page size to 10 and gets the second page of results.

Example: skip=10
limit
integer <int32> >= 0

Sets the number of objects to retrieve in a single request. If the limit parameter is not specified, the API returns all requested objects by default.

If limit is lower than the total number of objects matching your query, the next_page property in the pagination object of the API response will contain a URL to the next page of results.

The limit parameter affects only the number of items in the items property. It doesn't reduce the number of linked items in the modular_content property so you may hit the response size limit unexpectedly. You can set depth=0 to avoid that.

Example: limit=10
header Parameters
X-KC-Wait-For-Loading-New-Content
boolean

Determines whether the API waits while fetching latest content. By default, the header is not set and the API serves stale content (if cached by the CDN) while fetching the new content to minimize wait time.

The header can be useful if you know that the requested content had changed since your last request in a reaction to a webhook notification.

Example: false
Responses
200

A list of content types.

Request samples
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("<YOUR_ENVIRONMENT_ID>");

// Gets 3 content types
CompletionStage<ContentTypesListingResponse> types = client.getTypes(
    DeliveryParameterBuilder.params()
        .page(null, 3)
        .build()
    );
Response samples
application/json
{
  • "types": [
    • {
      • "system": {
        • "id": "b2c14f2c-6467-460b-a70b-bca17972a33a",
        • "name": "Article",
        • "codename": "article",
        • "last_modified": "2019-10-20T12:03:17.4685693Z"
        },
      • "elements": {
        • "multiple_choice": {
          },
        • "text": {
          },
        • "taxonomy": {
          }
        }
      }
    ],
  • "pagination": {}
}

Retrieve a content type

get/{environment_id}/types/{type_codename}

Retrieve a specific content type.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
type_codename
required
string

Identifies the content type by codename.

Example: article
query Parameters
elements
string

Determines a subset of the content type's elements to retrieve. The elements are specified using a comma-separated list of element codenames. By default, all elements are retrieved.

Examples

  • Retrieve a single element – elements=title
  • Retrieve multiple elements – elements=title,summary,related_articles

If the specified elements don't match the elements present in the content type, the API returns the content type without any elements.

The elements filter applies to all content types within the types array. The filter doesn't apply to the content types' system properties. This means you cannot omit the system object from the response.

Example: elements=title,summary
header Parameters
X-KC-Wait-For-Loading-New-Content
boolean

Determines whether the API waits while fetching latest content. By default, the header is not set and the API serves stale content (if cached by the CDN) while fetching the new content to minimize wait time.

The header can be useful if you know that the requested content had changed since your last request in a reaction to a webhook notification.

Example: false
Responses
200

A content type object.

404

The specified content type was not found.

Request samples
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("<YOUR_ENVIRONMENT_ID>");

// Gets a content type
CompletionStage<ContentType> type = client.getType("article");
Response samples
application/json
{
  • "system": {
    • "id": "b2c14f2c-6467-460b-a70b-bca17972a33a",
    • "name": "Article",
    • "codename": "article",
    • "last_modified": "2019-10-20T12:03:17.4685693Z"
    },
  • "elements": {
    • "multiple_choice": {
      • "type": "multiple_choice",
      • "name": "Multiple choices",
      • "options": [
        • {
          },
        • {
          }
        ]
      },
    • "text": {
      • "type": "text",
      • "name": "Text element"
      },
    • "taxonomy": {
      • "type": "taxonomy",
      • "name": "Categories taxonomy",
      • "taxonomy_group": "categories"
      }
    }
}

Retrieve a content type element

get/{environment_id}/types/{type_codename}/elements/{element_codename}

Retrieve a content type element defined in a specific content type. Both the type and element must be specified by their codenames.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
type_codename
required
string

Identifies the content type by codename.

Example: article
element_codename
required
string

Identifies the element by codename within the specified content type.

The element's codename has no relation to the type of the element.

Example: processing
header Parameters
X-KC-Wait-For-Loading-New-Content
boolean

Determines whether the API waits while fetching latest content. By default, the header is not set and the API serves stale content (if cached by the CDN) while fetching the new content to minimize wait time.

The header can be useful if you know that the requested content had changed since your last request in a reaction to a webhook notification.

Example: false
Responses
200

A content element object.

404

The specified content element was not found.

Request samples
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("<YOUR_ENVIRONMENT_ID>");

// Gets the "title" content element from the "article" type using a simple request
CompletionStage<Element> element = client.getContentTypeElement("article", "title");
Response samples
application/json
{
  • "type": "asset",
  • "name": "Teaser image",
  • "codename": "teaser_image"
}

Languages

Languages let you create multilingual content. When you set up languages, you can get localized content items by using the language query parameter.

You can get a list of languages defined in your environment to dynamically create a language selector in your app, for example.

Use short machine-readable codenames

We strongly recommend that you use short, easily identifiable, and machine-readable codenames for your languages. For example, you can specify language codenames based on the IETF or one of the ISO-639 standards.

Language object

Provides metadata of a language in your environment.

object
id
string

The language's ID.

name
string

The language's name.

codename
string

The language's codename.

{
  • "system": {
    • "id": "00000000-0000-0000-0000-000000000000",
    • "name": "Default language",
    • "codename": "default"
    }
}

List languages

get/{environment_id}/languages

Retrieve a list of active languages. By default, the API returns all languages ordered alphabetically by codename.

Get only the languages you need

To retrieve specific languages, use the filtering parameters in your requests. For example, you can request two specific languages (using the [in] filter) or all but one language (using the [neq] filter).

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
query Parameters
skip
integer <int32> >= 0

Sets the number of objects to skip when requesting a list of objects. The skip parameter must be combined with the limit parameter to work. If skip is not specified, the API returns the first page of results.

You can combine the limit and skip parameters to specify page size and page number. For example, using limit=10&skip=10 sets the page size to 10 and gets the second page of results.

Example: skip=10
limit
integer <int32> >= 0

Sets the number of objects to retrieve in a single request. If the limit parameter is not specified, the API returns all requested objects by default.

If limit is lower than the total number of objects matching your query, the next_page property in the pagination object of the API response will contain a URL to the next page of results.

The limit parameter affects only the number of items in the items property. It doesn't reduce the number of linked items in the modular_content property so you may hit the response size limit unexpectedly. You can set depth=0 to avoid that.

Example: limit=10
order
string

Determines the order of the retrieved objects. By default, the objects are sorted alphabetically by their codenames from A to Z in descending order.

To sort the requested objects in ascending order, set the order to <property_name>[asc] where <property_name> is the name of the object property you want to sort by. For example, order=elements.title[asc] or order=system.codename[asc]. Similarly, to sort in descending order, use the [desc] modifier. You can sort by any properties in the API response.

Examples

  • Sort by date – order=system.last_modified[desc]
  • Sort by a content item name – order=system.name[asc]
  • Sort by an element value – order=elements.<element_codename>[asc]
Example: order=system.last_modified[desc]
Responses
200

A list of active languages matching the specified parameters.

Request samples
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
const KontentDelivery = require('@kontent-ai/delivery-sdk');

const deliveryClient = KontentDelivery.createDeliveryClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>'
});

const response = await deliveryClient.languages()
  .limitParameter(3)
  .toPromise();
Response samples
application/json
{
  • "languages": [
    • {
      • "system": {
        • "id": "00000000-0000-0000-0000-000000000000",
        • "name": "Default language",
        • "codename": "default"
        }
      },
    • {
      • "system": {
        • "id": "614d82f5-c16c-465b-a34b-a37a1b416d12",
        • "name": "German",
        • "codename": "de-DE"
        }
      },
    • {
      • "system": {
        • "id": "de7bffee-659e-495f-b462-073974c88147",
        • "name": "English",
        • "codename": "en-US"
        }
      }
    ],
  • "pagination": {}
}

Taxonomy groups

Taxonomies are a versatile tool for categorizing and organizing your content.

Learn more about the use cases for taxonomies and see how to retrieve content tagged with a specific taxonomy term.

Taxonomy group object

required
object

The taxonomy group's system properties.

required
Array of objects unique

A list of taxonomy terms.

{
  • "system": {
    • "id": "f30c7f72-e9ab-8832-2a57-62944a038809",
    • "name": "Programming language",
    • "codename": "programming_language",
    • "last_modified": "2019-08-31T09:41:06.520241Z"
    },
  • "terms": [
    • {
      • "name": "C#",
      • "codename": "c_",
      • "terms": [ ]
      },
    • {
      • "name": "JavaScript",
      • "codename": "javascript",
      • "terms": [ ]
      }
    ]
}

List taxonomy groups

get/{environment_id}/taxonomies

Retrieve a paginated list of taxonomy groups. By default, the API returns all taxonomy groups ordered alphabetically by codename.

You can customize pagination by specifying both the skip and limit query parameters.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
query Parameters
skip
integer <int32> >= 0

Sets the number of objects to skip when requesting a list of objects. The skip parameter must be combined with the limit parameter to work. If skip is not specified, the API returns the first page of results.

You can combine the limit and skip parameters to specify page size and page number. For example, using limit=10&skip=10 sets the page size to 10 and gets the second page of results.

Example: skip=10
limit
integer <int32> >= 0

Sets the number of objects to retrieve in a single request. If the limit parameter is not specified, the API returns all requested objects by default.

If limit is lower than the total number of objects matching your query, the next_page property in the pagination object of the API response will contain a URL to the next page of results.

The limit parameter affects only the number of items in the items property. It doesn't reduce the number of linked items in the modular_content property so you may hit the response size limit unexpectedly. You can set depth=0 to avoid that.

Example: limit=10
header Parameters
X-KC-Wait-For-Loading-New-Content
boolean

Determines whether the API waits while fetching latest content. By default, the header is not set and the API serves stale content (if cached by the CDN) while fetching the new content to minimize wait time.

The header can be useful if you know that the requested content had changed since your last request in a reaction to a webhook notification.

Example: false
Responses
200

A paginated list of taxonomy groups.

Request samples
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("<YOUR_ENVIRONMENT_ID>");

// Gets 3 taxonomy groups
CompletionStage<List<TaxonomyGroup>> taxonomies = client.getTaxonomyGroups(
    DeliveryParameterBuilder.params()
        .page(null, 3)
        .build()
    ).thenApply(taxonomyGroupListingResponse -> taxonomyGroupListingResponse.getTaxonomies());
Response samples
application/json
{
  • "taxonomies": [
    • {
      • "system": {
        • "id": "f30c7f72-e9ab-8832-2a57-62944a038809",
        • "name": "Programming language",
        • "codename": "programming_language",
        • "last_modified": "2019-08-31T09:41:06.520241Z"
        },
      • "terms": [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "pagination": {}
}

Retrieve a taxonomy group

get/{environment_id}/taxonomies/{taxonomy_group_codename}

Retrieve a taxonomy group by its codename.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
taxonomy_group_codename
required
string

Identifies the taxonomy group by codename.

Example: personas
header Parameters
X-KC-Wait-For-Loading-New-Content
boolean

Determines whether the API waits while fetching latest content. By default, the header is not set and the API serves stale content (if cached by the CDN) while fetching the new content to minimize wait time.

The header can be useful if you know that the requested content had changed since your last request in a reaction to a webhook notification.

Example: false
Responses
200

A taxonomy group object.

404

The specified taxonomy group was not found.

Request samples
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("<YOUR_ENVIRONMENT_ID>");

// Gets a specific taxonomy group
CompletionStage<TaxonomyGroup> personas = client.getTaxonomyGroup("personas");
Response samples
application/json
{
  • "system": {
    • "id": "f30c7f72-e9ab-8832-2a57-62944a038809",
    • "name": "Programming language",
    • "codename": "programming_language",
    • "last_modified": "2019-08-31T09:41:06.520241Z"
    },
  • "terms": [
    • {
      • "name": "C#",
      • "codename": "c_",
      • "terms": [ ]
      },
    • {
      • "name": "JavaScript",
      • "codename": "javascript",
      • "terms": [ ]
      }
    ]
}