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.

Uncover the basics of Delivery API

Check out our 20-minute course introducing Delivery API.

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, use:
    https://preview-deliver.kontent.ai/<YOUR_PROJECT_ID>/
  • To retrieve published content from your project, use:
    https://deliver.kontent.ai/<YOUR_PROJECT_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 project.

Postman collection

Try the Kontent.ai APIs with Postman! 📫 The Postman collection is regularly updated and contains endpoints for all Kontent.ai APIs, just like you see in the API references.

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

Bearer authentication

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 shared API key. With advanced asset management, you can also secure access to your assets.

To authenticate against the API, send your requests over HTTPS and use the Authorization header in the following format: Authorization: Bearer <YOUR_API_KEY>. Find your API keys in 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_API_KEY>"

API keys

When you activate secure access for your project, Delivery API starts requiring an API key with each API request for content. Also, Kontent.ai generates two API keys – Primary key and Secondary key.

Quick facts about the Primary and Secondary keys

  • The scope of the API keys is per environment.
  • Their default expiration date is 1 year.
  • Use the Primary key for continuous use in your apps.
  • Use the Secondary key when revoking the Primary key to prevent downtime.

Expiration

The API key expiration length is set to 1 year by default. 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.

Expiration reminder

5 days before the API key's expiration date, we'll send a notification email to users with the Manage APIs permission.

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. You cannot revoke an API key without generating a new one.

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

Scope

The scope of the API key is per environment. This means the API key is shared among the users who have the Manage APIs permission and can access the project's environment. This applies to both Delivery API and Delivery Preview API.

API limitations

API requests limit

Delivery API requests, that is requests for published content, count towards the overall API Calls limit set in our Fair Use Policy.

Delivery Preview API requests, that is requests for previewing latest and/or unpublished content, do NOT count towards the API Calls limit.

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 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 goes through 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 project localization settings

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

If you change a project language's codename, the API needs to process all items that have content in that language. Until this 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. You can make an unlimited number of requests to the CDN.

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. Such 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 project 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 a response with the contents of content item A and its linked items. That response with content item A is cached in the CDN. If you make changes to content item A, the cached response is removed from the cache. If the CDN had previously cached other responses that contained content of content item A, these responses are removed from the cache as well.

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 your request for a missing required parameter or an invalid query parameter value.
401 Unauthorized The provided API key expired, is in the wrong format, or is missing. Try copying and using the current API key for your project.
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.

Filter by system values

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

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


.
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-01elements.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-01elements.price[lte]=4 Simple types
[gt] Property value is greater than the specified value. See Comparing values. system.last_modified[gt]=2019-01-01elements.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-28elements.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-31elements.price[range]=10.5,50 Simple types
[in] Property value is in the specified list of values. system.type[in]=cafe,coffeeelements.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.

Allowed values: "Africa/Abidjan" "Africa/Accra" "Africa/Addis_Ababa" … 634 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

In the modular_content object property of the Delivery API response, you can find the contents of the linked content items and content components.

In the rich text element's modular_content array property, you can find the codenames of the inserted content items and content components.

The codenames in the rich text's modular_content array are grouped and ordered. First comes a group of 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 element does not contain any content, its value defaults to a single empty paragraph: <p><br></p>.

{
  • "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>"
}

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.

Two distinct modular_content properties

In the modular_content object property of the Delivery API response, you can find the contents of the linked content items and content components.

In the rich text element's modular_content array property, you can find the codenames of the inserted content items and content components.

The codenames in the rich text's modular_content array are grouped and ordered. First comes a group of item codenames followed by a group of component codenames. The order of codenames in each group matches that in the UI.

<!-- 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. To retrieve specific items from your project, either provide a codename for one item or filter all items using parameters. By default, the Delivery 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_step": "published"
    },
  • "elements": {
    • "<element_codename>1": {
      • "type": "asset",
      • "name": "Teaser image",
      • "value": [
        • {
          }
        ]
      },
    • "<element_codename>2": {
      • "type": "asset",
      • "name": "Teaser image",
      • "value": [
        • {
          }
        ]
      }
    }
}

List content items

get/{project_id}/items

Retrieve a list of content items from your project. By default, the API returns an unfiltered paginated list of content items 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 from your project, we recommend using the Enumerate content items endpoint.

You can change the order by specifying the order query parameter. You can customize pagination by specifying both the skip and limit query parameters. Note that the limit parameter affects only the items property, not modular_content.

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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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 of your project.

Example: language=en-US
elements
string

Determines a subset of the content item'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 item, the API returns the content item without any elements.

The elements filter applies to all content items within the response, that is both the items array and modular_content object property. The filter doesn't apply to the content item's system properties. This means you cannot omit the system object from the response.

Example: elements=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_PROJECT_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_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_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_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_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_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/{project_id}/items/{item_codename}

Retrieve a specific content item by specifying its codename.

The response size is limited to 2000 items.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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 of your project.

Example: language=en-US
elements
string

Determines a subset of the content item'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 item, the API returns the content item without any elements.

The elements filter applies to all content items within the response, that is both the items array and modular_content object property. The filter doesn't apply to the content item's system properties. This means you cannot omit the system object from the response.

Example: elements=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_PROJECT_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_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_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/{project_id}/items-feed

Retrieve a dynamically paginated list of content items in your project. The items are 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.

This endpoint, unlike the List content items endpoint, guarantees to enumerate all content items in the specified project. 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.

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.

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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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 of your project.

Example: language=en-US
elements
string

Determines a subset of the content item'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 item, the API returns the content item without any elements.

The elements filter applies to all content items within the response, that is both the items array and modular_content object property. The filter doesn't apply to the content item's system properties. This means you cannot omit the system object from the response.

Example: elements=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({
  projectId: '<YOUR_PROJECT_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_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_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_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/{project_id}/types

Retrieve a paginated list of content types in your project. 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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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_PROJECT_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/{project_id}/types/{type_codename}

Retrieve a specific content type.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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_PROJECT_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/{project_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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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 JS/TS SDKs at https://kontent.ai/learn/javascript
const KontentDelivery = require('@kontent-ai/delivery-sdk');

const deliveryClient = KontentDelivery.createDeliveryClient({
  projectId: '<YOUR_PROJECT_ID>'
});

const response = await deliveryClient.element('article', 'title')
  .toPromise();
Response samples
application/json
{
  • "type": "asset",
  • "name": "Teaser image",
  • "codename": "teaser_image"
}

Languages

Languages let you create multilingual content. If you've set up languages for your project, you can get localized content for each content item by using the language query parameter. You can also get languages from your project 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

A language in your project.

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 project language",
    • "codename": "default"
    }
}

List languages

get/{project_id}/languages

Retrieve a list of active languages from your project. 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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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({
  projectId: '<YOUR_PROJECT_ID>'
});

const response = await deliveryClient.languages()
  .limitParameter(3)
  .toPromise();
Response samples
application/json
{
  • "languages": [
    • {
      • "system": {
        • "id": "00000000-0000-0000-0000-000000000000",
        • "name": "Default project 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/{project_id}/taxonomies

Retrieve a paginated list of taxonomy groups in your project. 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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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_PROJECT_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/{project_id}/taxonomies/{taxonomy_group_codename}

Retrieve a specific taxonomy group specified by codename.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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_PROJECT_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": [ ]
      }
    ]
}