Use the API to deliver large amounts of content to your website or app. The content is cached on the CDN level, which makes it quickly available from wherever you are. The Delivery API provides content filtering options that allow you to retrieve only the parts of the content you need.

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

You can work with the Delivery API in two ways – either retrieve published versions of content items or preview their yet unpublished versions. In both cases, you use the same methods to request data but with a different base URL.

Retrieve published content items from your project using the production URL:
https://deliver.kontent.ai/<YOUR_PROJECT_ID>/items

Note: To protect your published content, use the Delivery API with secure access enabled.

Preview unpublished content items from your project using the preview URL:
https://preview-deliver.kontent.ai/<YOUR_PROJECT_ID>/items

If you want to preview unpublished content in your project, you need to authorize your request.

cURL
curl --request GET \
  --url https://preview-deliver.kontent.ai/975bf280-fd91-488c-994c-2f04416e5ee3/items/on_roasts \
  --header 'authorization: Bearer <YOUR_PREVIEW_API_KEY>'

JavaScript
// Tip: Find more about JS/TS SDKs at https://docs.kontent.ai/javascript
const KontentDelivery = require('@kentico/kontent-delivery');
 
// Create strongly typed models according to https://docs.kontent.ai/strongly-typed-models
class Article extends KontentDelivery.ContentItem {
    constructor() {
        super();
    }
}
 
const deliveryClient = new KontentDelivery.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    previewApiKey: '<YOUR_PREVIEW_API_KEY>',
    globalQueryConfig:  {
        usePreviewMode: true, // Queries the Delivery Preview API.
    },
    typeResolvers: [
        new KontentDelivery.TypeResolver('article', (rawData) => new Article)
    ]
});
 
deliveryClient.item('on_roasts')
    .toObservable()
    .subscribe(response => console.log(response));

TypeScript
// Tip: Find more about JS/TS SDKs at https://docs.kontent.ai/javascript
import { ContentItem, DeliveryClient, Elements, TypeResolver } from '@kentico/kontent-delivery';
 
// Create strongly typed models according to https://docs.kontent.ai/tutorials/develop-apps/get-content/using-strongly-typed-models
export class Article extends ContentItem {
    public title: Elements.TextElement;
    public summary: Elements.TextElement;
    public post_date: Elements.DateTimeElement;
    public teaser_image: Elements.AssetsElement;
    public related_articles: Article[];
}
 
const deliveryClient = new DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    previewApiKey: '<YOUR_PREVIEW_API_KEY>',
    globalQueryConfig:  {
        usePreviewMode: true, // Queries the Delivery Preview API.
    },
    typeResolvers: [
        new TypeResolver('article', (rawData) => new Article)
    ]
});
 
deliveryClient.item<Article>('on_roasts')
    .toObservable()
    .subscribe(response => console.log(response));

C#
// Tip: Find more about .NET SDKs at https://docs.kontent.ai/net
using Kentico.Kontent.Delivery;
 
// Initializes a delivery client for previewing content
IDeliveryClient client = DeliveryClientBuilder
    .WithOptions(builder => builder
        .WithProjectId("975bf280-fd91-488c-994c-2f04416e5ee3")
        .UsePreviewApi("<YOUR_PREVIEW_API_KEY>")
        .Build())
    .Build();
 
// Generate strongly typed models via https://github.com/Kentico/cloud-generators-net
DeliveryItemResponse response = await client.GetItemAsync("on_roasts");
ContentItem item = response.Item;

Java
// Tip: Find more about Java/JavaRx SDKs at https://docs.kontent.ai/javaandroid
import com.github.kentico.kontent.delivery;
 
DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3", "<YOUR_PREVIEW_API_KEY>");
 
ContentItem item = client.getItem("on_roasts").item;

Java
// Tip: Find more about Java/JavaRx SDKs at https://docs.kontent.ai/javaandroid
import com.kenticocloud.delivery_core.*;
import com.kenticocloud.delivery_rx.*;
 
import io.reactivex.Observer;
import io.reactivex.disposables.Disposable;
import io.reactivex.functions.Function;
 
// Prepares an array to hold strongly-typed models
List<TypeResolver<?>> typeResolvers = new ArrayList<>();
 
// Registers the type resolver for articles
typeResolvers.add(new TypeResolver<>(Article.TYPE, new Function<Void, Article>() {
    @Override
    public Article apply(Void input) {
        return new Article();
    }
}));
 
// Prepares the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
String previewApiKey = "<YOUR_PREVIEW_API_KEY>";
 
IDeliveryConfig config = DeliveryConfig.newConfig(projectId)
    .withTypeResolvers(typeResolvers)
    .withPreviewApiKey(previewApiKey);
 
// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);
 
// Gets the latest version of an article using a simple request
Article article = deliveryService.<Article>item("on_roasts")
    .get()
    .getItem();
 
// Gets the latest version of an article using RxJava2
deliveryService.<Article>item("on_roasts")
    .getObservable()
    .subscribe(new Observer<DeliveryItemResponse<Article>>() {
        @Override
        public void onSubscribe(Disposable d) {
        }
 
        @Override
        public void onNext(DeliveryItemResponse<Article> response) {
            // Get the article
            Article item = response.getItem();
        }
 
        @Override
        public void onError(Throwable e) {
        }
 
        @Override
        public void onComplete() {
        }
    });

Swift
// Tip: Find more about Swift SDK at https://docs.kontent.ai/ios
import KenticoCloud
 
let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3", apiKey: "<YOUR_PREVIEW_API_KEY>")
 
// More about strongly-typed models https://github.com/Kentico/cloud-sdk-swift#using-strongly-typed-models
client.getItem(modelType: Article.self, itemName: "on_roasts") { (isSuccess, itemResponse, error) in
    if isSuccess {
        if let article = itemResponse.item {
            // Use your item here
        }
    } else {
        if let error = error {
            print(error)
        }
    }
}

PHP
<?php
// Tip: Find more about PHP SDKs at https://docs.kontent.ai/php
 
// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';
 
use Kentico\Kontent\Delivery\DeliveryClient;
 
$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3', '<YOUR_PREVIEW_API_KEY>');
 
$item = $client->getItem('on_roasts');

Ruby
require 'delivery-sdk-ruby'
 
delivery_client = Kentico::Kontent::Delivery::DeliveryClient.new project_id: '975bf280-fd91-488c-994c-2f04416e5ee3',
                    preview_key: '<YOUR_PREVIEW_API_KEY>'
delivery_client.item('on_roasts').execute do |response|
  puts response.to_s
end

For the Delivery Preview API, you can use two concurrent API keys, Primary and Secondary. For more details on how to work with the keys, see Previewing unpublished content.

By default, the Delivery API does not require authentication. However, if you enable secure access for the Delivery API or use the Delivery Preview API, you need to authenticate your requests with valid API keys.

To work with the Delivery API with secure access enabled or the Delivery Preview API, send your requests over HTTPS using the Authorization header in the following format: Authorization: Bearer <YOUR_API_KEY>. Requests with an incorrect or missing Authorization header will fail with an error.

To get your API key for the API, go to Kentico Kontent -> Project settings -> API keys. The API keys provide access to a single Kentico Kontent project. You will need different API keys for each of your projects.

Kentico Kontent returns standard HTTP status codes to indicate success or failure of a request. In general, codes in the 2xx range indicate a successful request, codes in the 4xx range indicate errors caused by an incorrect input (for example, providing incorrect API key), and codes in the 5xx range indicate an error on our side.

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

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

The Delivery API does not require authentication by default but you can enable secure access for the project to force authenticated requests.

With secure access, you can use two concurrent API keys, Primary and Secondary. For more details on how to work with the keys, see Securing public access.

As the Delivery API is designed for continuous retrieval of published content, there is no expiration date for the Primary or Secondary API key.

The API keys are scoped per project. This means you need a separate API key for each project in Kentico Kontent. All users within a single project share the same Delivery API keys.

The Delivery API with secure access enabled and the Delivery Preview API both use two concurrent API keys, Primary and Secondary. In certain situations, you may need to revoke one of these keys and generate a new one. For example, when you suspect unauthorized key use or when a developer with access to the API key has left your company.

For situations like these, one or both of the API keys can be regenerated. Activating a new key will immediately replace the old key. Requests made with a revoked API key will then receive a 401 Unauthorized HTTP status in the response.

When retrieving content items from your project, you can filter large sets of content items by building query parameters from content elements and system properties. Note that filtering does NOT apply to content items returned within the modular_content collection.

If you want to get only a specific set of elements from content items, use projection when retrieving the items.

Filtering 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, name, codename, language, type, sitemap_locations, and last_modified. For example, to retrieve only content items based on the Article content type, use system.type=article as a query parameter.

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

Joining multiple query parameters

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

For example, the query system.type=article&elements.persona[contains]=barista will return the content items of the Article type that are tagged with the Barista taxonomy term.

Filtering operators

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

Note that all of the operators are case-sensitive.

Arrays vs. simple types

You can use the [contains], [any], and [all] filtering operators only on array properties. The supported array properties include the sitemap locations within the system object of content items, and the linked items, multiple choice, and taxonomy elements.

Note: Asset elements are not supported with [contains], [any], and [all] filtering operators.

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.

When getting content items or content types, you can specify which elements to return by using the elements query parameter.

• For items, the parameter applies to content items returned within both the items array and modular_content collection.
• For types, the parameter applies to content types returned within the types array.

Examples

By using elements=title as a query parameter, the elements collection in each content item will contain only the element with the codename title, or, if the item doesn't have an element with such codename, the elements collection will be empty.

For multiple elements, you can use a query parameter such as elements=title,summary,related_articles to retrieve only the elements with codenames title, summary, and related_articles.

Note: Projection does not apply to the system properties. This means that you cannot omit the system object from the response using any query.

Kentico Kontent offers a variety of ways to compose, structure, and cross-reference your content:

• Linked items elements are used to reference other content items.
• Rich text elements can also contain content items. Useful for inserting content into a specific point in the text.
• Rich text elements can contain components.
  • A component is a single-use content item.
  • It has the same structure as a content item.
  • It is based on a specific content type.
  • Unlike a content item, a component only exists inside its Rich text element. Learn more about using components.

When retrieving items using the Delivery API, the contents of all components and content items in rich text and linked items elements are stored as properties in a separate modular_content object within the API response. The properties of the modular_content object (i.e., individual components and items) are not ordered. See linked items and rich text elements for details on how ordering is done within the elements.

When enumerating the items in your project using the Delivery API, the modular_content collection in the response will contain only components, not content items used in linked items elements.

Note: For historical reasons, the object is called "modular_content" instead of "linked_content".

Linked content depth

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

• If you want to include more than one level of linked items in response, set the depth query parameter to 2 or more.
• If you want to exclude all linked items, use the depth=0 query parameter.
• When retrieving content, linked items cannot be filtered.

Components are not affected by the depth parameter as they are an integral part of their Rich text element. They are always present in the response. You can only nest components up to depth level 6.

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.