Suggest Edits

Introduction

 

The Kentico Cloud APIs are built around the REST principle and return content in JSON. We provide example requests in Curl and .NET, and example responses in JSON for all endpoints.

API overview

API name API resource Use case
Delivery API https://deliver.kenticocloud.com/<YOUR_PROJECT_ID>/
https://preview-deliver.kenticocloud.com/<YOUR_PROJECT_ID>/
Get content from Kentico Cloud to your web applications and mobile applications.
Content Management API https://manage.kenticocloud.com/projects/<YOUR_PROJECT_ID> Manage content items in Kentico Cloud projects, or import your existing content from a different system.
Migration API https://api.kenticocloud.com/draft/ Migrate content and content models from Kentico Cloud to a platform of your choice.

Trying out the endpoints

You can try out the APIs either using Postman or directly on this page.

Run in Postman

For each endpoint, you can also use the Try it button to see what the endpoint returns in real time.

Try any of the endpoints

Try any of the endpoints

Suggest Edits

Authentication

How and when to authenticate your requests.

 

Authenticate requests to the Kentico Cloud APIs by using API keys. To find the keys in Kentico Cloud, under Project settings, navigate to the API keys section.

An API key provides access to a single Kentico Cloud project, you will need to use a different API key for each project.

Which APIs need authentication?

You need to authenticate your requests when calling the following Kentico Cloud APIs:

To retrieve content from these APIs, send your requests over HTTPS and authenticate with an OAuth 2.0 bearer token using the Authorization header in the following format:

Authorization: Bearer <YOUR_API_KEY>

Calls with an incorrect or missing Authorization header will fail with an error.

Suggest Edits

Error responses

Status codes and error responses you can encounter when using the API.

 

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

HTTP error code 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 is invalid or missing. See Authentication.
403
Forbidden
The provided API key is invalid for the requested project.
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. Try performing a GET request.
500
Internal Server Error
Something went wrong on our side. Try the request again in a few minutes, or contact us.

Resolving errors

For troubleshooting failed requests, the Kentico Cloud APIs provide error messages defined in a consumable format to help you identify and fix the issue. For example, when you request a content item that does not exist (for example, you mistyped its codename), the API returns a 404 HTTP error along with a JSON message.

If you cannot identify and resolve an issue with your API call, you can contact us with the response status and the unique error ID. Hint: use the chat button in the bottom right corner of this page.

Example: Mistyped codename of a content item

{
  "message": "The requested content item 'on_roatst' was not found.",
  "request_id": "HyufT6wUgEc=",
  "error_code": 100,
  "specific_code": 0
}

Example: Invalid value of a query parameter

{
  "message": "Query parameter 'limit' must be a positive integer.",
  "request_id": "GMAQvDLeLbE=",
  "error_code": 1005,
  "specific_code": 0
}
Suggest Edits

Delivery API

 

The Delivery API is a read-only REST API that serves published content from your Kentico Cloud projects.

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.

API requests limits

Requests made to the Delivery API count towards the overall API Calls limit set in our Fair Use Policy. This does NOT apply to Delivery Preview API calls to preview unpublished content.

Production vs. Preview

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.kenticocloud.com/<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.kenticocloud.com/<YOUR_PROJECT_ID>/items

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

curl --request GET \
  --url https://preview-deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/items/on_roasts \
  --header 'authorization: Bearer <YOUR_PREVIEW_API_KEY>'
using KenticoCloud.Delivery;

DeliveryOptions deliveryOptions = new DeliveryOptions
{
    ProjectId = "975bf280-fd91-488c-994c-2f04416e5ee3",
    PreviewApiKey = "<YOUR_PREVIEW_API_KEY>"
}

DeliveryClient client = new DeliveryClient(deliveryOptions);

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-net
DeliveryItemResponse<object> response = await client.GetItemAsync<object>("on_roasts");

var items = response.Items;
const KenticoCloud = require('kentico-cloud-delivery');

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    enablePreviewMode: true,
    previewApiKey: "<YOUR_PREVIEW_API_KEY>",
    typeResolvers: [
        new KenticoCloud.TypeResolver('article', () => new Article)
    ]
});

deliveryClient.item('on_roasts')
    .getObservable()
    .subscribe(response => console.log(response));
import { ContentItem, DeliveryClient, Fields, TypeResolver } from 'kentico-cloud-delivery';

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
export class Article extends ContentItem {
    public title: Fields.TextField;
    public summary: Fields.TextField;
    public post_date: Fields.DateTimeField;
    public teaser_image: Fields.AssetsField;
    public related_articles: Article[];
}

const deliveryClient = new DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    enablePreviewMode: true,
    previewApiKey: "<YOUR_PREVIEW_API_KEY>",
    typeResolvers: [
        new TypeResolver('article', () => new Article)
    ]
});

deliveryClient.item<Article>('on_roasts')
    .getObservable()
    .subscribe(response => console.log(response));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3", "<YOUR_PREVIEW_API_KEY>");

ContentItem item = client.getItem("on_roasts").item;
import com.kenticocloud.delivery_core.*;
import com.kenticocloud.delivery_rx.*;

import io.reactivex.Observer;
import io.reactivex.disposables.Disposable;
import io.reactivex.functions.Function;

// Generate strongly-typed models via https://github.com/Kentico/cloud-generators-java
// Prepares an array to hold the 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() {
        }
    });
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3', '<YOUR_PREVIEW_API_KEY>');

$item = $client->getItem('on_roasts');
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)
        }
    }
}

For more details on retrieving unpublished content, see Previewing content via API.

Suggest Edits

Listing response

Object model descriptions of the listing responses (for content items, content types, and taxonomies) returned by the Delivery API.

 

When you retrieve a list of content items, content types or taxonomy groups from your project, the Delivery API returns a paginated listing response. To request a specific page of the listing response, you need to customize the pagination parameters.

Content items listing response

Attribute Description Type
items A list of content items array of Content item objects
modular_content A list of components and content items used in Rich text and Linked items elements. See Linked content and components for more details. collection of Content item objects
pagination Information about the retrieved page Pagination

Content types listing response

Attribute Description Type
types A list of content types array of Content type objects
pagination Information about the retrieved page Pagination

Taxonomy listing response

Attribute Description Type
taxonomies A list of taxonomy groups array of Taxonomy group objects
pagination Information about the retrieved page Pagination

Pagination object

Attribute Description Type Notes
skip Number of content items skipped from the response integer Reflects the value set by the skip query parameter.
limit Number of content items returned in the response integer Reflects the value set by the limit query parameter.
count Number of retrieved content items integer If the limit and skip query parameters aren't set, the count attribute will contain the total number of content items matching the specified filtering parameters.
next_page URL to the next page of results string See Paging for more details.

Example: Content items listing

{
  "items": [
    # array of Content item objects
  ],
  "modular_content": {
    # list of Content item objects (including component objects)
  },
  "pagination": {
    "skip": 0,
    "limit": 10,
    "count": 10,
    "next_page": "https://deliver.kenticocloud.com/<YOUR_PROJECT_ID>/items?limit=10&skip=10"
  }
}

Example: Content types listing

{
  "types": [
    # array of Content type objects
  ],
  "pagination": {
    "skip": 0,
    "limit": 3,
    "count": 3,
    "next_page": "https://deliver.kenticocloud.com/<YOUR_PROJECT_ID>/types?limit=3&skip=3"
  }
}

Example: Taxonomy group listing

{  
  "taxonomies":[ 
    # array of Taxonomy group objects
  ],
  "pagination":{  
    "skip":0,
    "limit":0,
    "count":3,
    "next_page":"https://deliver.kenticocloud.com/<YOUR_PROJECT_ID>/taxonomy?limit=3&skip=3"
  }
}
Suggest Edits

Filtering

Retrieve a filtered listing response from your project by specifying filtering parameters.

 

When retrieving a list of content items from your project, you can filter large sets of content items by building query parameters from content elements and system attributes. Note that filtering does NOT apply to content items returned within the modular_content collection (see Content items listing response).

If you want to limit the elements in the listing response only to specific elements, see Projection.

Filtering by system values

To filter by system attribute values, you need to use a query parameter in the system.<attribute_name> format. The system attributes include id, name, codename, type, sitemap_locations, and last_modified. For example, to retrieve only content items based on the Article content type, you can 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, you can use elements.price=16 as a query parameter.

Joining multiple query parameters

You can join multiple query parameters by 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, query system.type=article&system.sitemap_locations[contains]=cafes will return the Article content items which are in the Cafes section of the project sitemap.

Filtering operators

You can use the following filtering operators both with the system attributes and element values:

Operator
Description
Example
Use with

=

Attribute value is the same as the specified value.

system.type=article

Simple types

[lt]

Attribute value is less than the specified value.

More in Comparing values.

system.last_modified[lt]=2018-03-01
elements.price[lt]=10

Simple types

[lte]

Attribute value is less than or equals the specified value.

More in Comparing values.

system.last_modified[lte]=2018-02-01
elements.price[lte]=4

Simple types

[gt]

Attribute value is greater than the specified value.

More in Comparing values.

system.last_modified[gt]=2018-01-01
elements.price[gt]=1000

Simple types

[gte]

Attribute value is greater than or equals the specified value.

More in Comparing values.

system.last_modified[gte]=2018-02-28
elements.price[gte]=50

Simple types

[range]

Attribute value falls in the specified range of two values, both inclusive.

More in Comparing values.

system.last_modified[range]=2018-02-01,2018-03-31
elements.price[range]=10.5,50

Simple types

[in]

Attribute value is in the specified list of values.

system.type[in]=cafe,coffee
elements.price[in]=8.5,9,10.5

Simple types

[contains]

Attribute with an array of values contains the specified value.

system.sitemap_locations[contains]=cafes

Arrays

[any]

Attribute with an array of values contains any value from the specified list of values.

elements.personas[any]=barista,coffee_blogger

Arrays

[all]

Attribute with an array of values contains the specified list of values.

elements.personas[all]=barista,coffee_blogger

Arrays

Arrays vs. simple types

You can use the [contains], [any], and [all] filtering operators only with arrays. Array attributes in Kentico Cloud include the sitemap locations system object, and the Asset, Modular content, Multiple choice, and Taxonomy content elements. All the other system attributes and content type elements are simple types, such as strings or numbers.

Comparing values

The filtering operators [lt], [lte], [gt], [gte], and [range] work best with numbers. For example, you can retrieve products with price larger or equal to 15 by using elements.price[gte]=15. Attributes that store dates (such as the last_modified system attribute or Date & time elements) are represented as strings.

If you use the filters on attributes with string values, the Delivery API tries to perform a string comparison. For example, to retrieve content items modified during February and March you'd need to use a query such as system.last_modified[range]=2018-02-01,2018-03-31, specifying both the start and end dates.

Suggest Edits

Ordering

Sort the content in a listing response.

 

You can sort the listing response by using the order query parameter. As with filtering, you can use both the system and elements attributes to sort data.

To sort content items in the ascending order, add the order=<attribute>[asc] query parameter. Similarly, to sort in the descending order, you can use the [desc] modifier.

Examples

  • Sort by date – order=system.last_modified[asc]
  • Sort by content item name – order=system.name[asc]
  • Sort by element value – order=elements.<element_codename>[desc]

You can get only a small subset of a large collection of content items with the skip and limit query parameters. Using these parameters, you can display a specific page of results and iterate over a list of content items or types.

For example, when you have a listing response with a page size of 10 items, you can use the skip=10&limit=10 query parameters to retrieve the second page of results.

For details about the pagination data in each listing response, see the Pagination object.

Suggest Edits

Projection

Choose specific content elements to retrieve when getting content items.

 

You can specify which elements to return by using the elements query parameter. With regards to the listing response, the elements query parameter applies both to content items returned within the items array and modular_content collection.

Using projection

By using elements=title as a query parameter when getting content items, the elements collection in each content item will contain only the element with 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 attributes. You cannot omit the System object from the JSON response by using any query.

Suggest Edits

Linked content and components

 

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

  • Linked items element is used to reference other content items.
  • Rich text element can also contain content items. Useful for inserting content into a specific point in the text.
  • Rich text element 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 at our Help Center.

When retrieving items using Delivery API, the contents of all components and content items in Rich text and Linked items elements are stored in a separate modular_content property of the response. Note that the property is called "modular_content" instead of "linked_content" for historical and backward-compatibility reasons.

Linked content depth

Content items reference other content items using the Linked items or Rich text element. Recursively, these linked items can link to other items. By default, only one level of linked items is returned.

  • If you want to include more than one level of linked items in response, use the depth query parameter.
  • 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. Kentico Cloud will only let users nest components up to depth level 6.

Suggest Edits

Secure access

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

 

Premium feature

Secure access to the Delivery API requires a Professional plan or higher. See Pricing for more details.

With the secure access enabled for the Delivery API, 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 scope of the API keys is per project. This means you need a separate API key for each project in Kentico Cloud. All of the users contributing to the same project share the API keys.

Suggest Edits

Revoking the API keys

Revoke one or both the API keys and generate new ones.

 

The Delivery API with secure access enabled uses 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 code in the response.

There is no expiration date for the Primary or Secondary API key. However, we recommend you regenerate the API keys periodically to prevent the keys from being compromised. Learn more in Securing public access.

Example: API key revocation

{
  "message": "Missing or invalid access token. Please include the valid access token value in the Authorization header field as an HTTP bearer authorization scheme.",
  "request_id": "|l9SYVqXWBcI=.5ac3a6df_",
  "error_code": 3,
  "specific_code": 0
}
Suggest Edits

Image transformation

Transform your images in real-time using Delivery API.

 

Image transformation is a real-time image manipulation and optimization feature of the Delivery API that speeds up image delivery. As Kentico Cloud caches the results of image transformation, you can retrieve the adjusted images even faster the next time you need them.

Input and output formats

In order to transform images stored in Kentico Cloud, the source images need to be in any of the following image formats:

  • jpeg, png, gif, and webp

You can also set the limitations in content types to only accept these adjustable image formats.

The optimized output image can be any of the following image formats:

  • jpg, pjpg, png, png8, gif, and webp

The format parameter allows you to convert the image by choosing the output format.

By adding parameters to your image URL, you can enhance, resize and crop images, compress them, or change the format for better performance. These operations can be applied programmatically in real time, removing the need to batch process or maintain multiple copies of an image to match device breakpoints.

Name Parameter Notes
Size
Width w Resize the width of the image.
Height h Resize the height of the image.
Device pixel ratio dpr Serve correctly sized images for devices that expose a device pixel ratio.
Resize fit mode fit Set how the image will fit within the size bounds provided.
Source rectangle region rect Select a sub-region of the source image to use for processing.
Focal point crop
Focal point crop fp-x, fp-y, fp-z Choose the point of interest of your image when cropping the image.
Format
Output format fm Specify the output format to convert the image to.
Quality q Optimize the image to the given compression level for lossy file formatted images.
Lossless lossless Enable delivery of lossless images in formats that support lossless compression.
Automatic format selection auto Automatic delivery of WebP format images.

Working with the image URLs

Image transformation works by applying the query parameters of the transformation methods to the absolute URLs of images. When image is added to the content item, the image URL can be retrieved via the Delivery API. You can get the image URLs by either listing the items or retrieving a single content item containing the images.

Adjustable images can be used in the Asset elements and in the Rich text elements of the content items. When in the Asset element, the absolute URL for the image can be found in the url attribute of an asset object returned in the JSON response. When in the Rich Text element, the absolute URL for the image can be found in the url attribute of the images object and in the formatted text of the value attribute.

"teaser_image": {
  "type": "asset",
  "name": "Teaser image",
  "value": [
    {
      "name": "coffee-beverages-explained-1080px.jpg",
      "type": "image/jpeg",
      "size": "90895",
      "description": null,
      // Absolute image URL
      "url": "https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/e700596b-03b0-4cee-ac5c-9212762c027a/coffee-beverages-explained-1080px.jpg"
    }
  ]
}
"description": {
  "type": "rich_text",
  "name": "Description",
  "images": {
    "14mio": {
      "image_id": "14mio",
      "description": "Roasting coffee beans",
      // Absolute image URL
      "url": "https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/roaster.jpg"
    }
  },
  "links": {
    "f4b3fc05-e988-4dae-9ac1-a94aba566474": {
      "type": "article",
      "codename": "on_roasts",
      "url_slug": ""
    }
  },
  "modular_content": [
    "coffee_processing_techniques"
  ],
  // Absolute image URL in the <img> tag
  "value": "<p>We operate our own roasteries, one on every continent we cover, from where we distribute right to the shops. This allows you to experience every cup as if you were right at the very farm it originated from. To achieve this, we use a refurbished 1920s Probat coffee roasters.</p>\n<figure data-image-id=\"14mio\"><img src=\"https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/roaster.jpg\" alt=\"Roasting coffee beans\" data-image-id=\"14mio\"></figure><p>We know that roasting is something you must keep on constantly perfecting. Each coffee requires a different roast to get the aroma and taste just right. That’s why our experts fine tune the way we <a data-item-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\" href=\"\">roast coffees</a> every day. It’s a constant struggle.</p><object type=\"application/kenticocloud\" data-type=\"item\" data-codename=\"coffee_processing_techniques\"></object>"
}
Suggest Edits

Size

Size parameters allow you to resize, crop, and change the aspect ratio of your images.

 

In general, when using an invalid combination of parameters for the image, the Delivery API returns the original image without applying any changes. The maximum output dimensions are 8192x8192 pixels. All output images will be sized down to accommodate this limit.

See also the tutorial on Optimizing images for web where the size parameters are used in a real-world scenario.

Image width (w)

Image width represents the width of the output image. The w parameter allows you to dynamically resize the image based on pixels and percent values. If the width is represented by an integer greater than or equal to 1, the value is interpreted as a pixel width. If the width is a float greater than 0 but less than 1, it's interpreted as a percentage width. The maximum output width can be 8192px. If both width and height parameters are omitted, the input image dimensions are used.

Value
Units
Description
Example

Integer

Pixels

A whole number between 1 and 8192.

Resize the width to 300px. /on-roasts-1080px.jpg?w=300

Float

Percentage

A floating-point number greater than 0 but less than 1.

Resize the width to 10% of the input image. /on-roasts-1080px.jpg?w=0.1

Note: It is not possible to upscale an image. When using a width parameter greater than the input image width, the Delivery API returns the original image without any changes to its width.

Image height (h)

Image height represents the height of the output image. The h parameter allows you to dynamically resize the image based on pixels and percent values. If the height is represented by an integer greater than or equal to 1, the value is interpreted as a pixel height. If the height is a float greater than 0 but less than 1, it's interpreted as a percentage height. The maximum output height can be 8192px. If both width and height are omitted, the input image dimensions are used.

Value
Units
Description
Example

Integer

Pixels

A whole number between 1 and 8192.

Resize the height to 300px. /on-roasts-1080px.jpg?h=300

Float

Percentage

A floating-point number greater than 0 but less than 1.

Resize the height to 10% of the input image. /on-roasts-1080px.jpg?h=0.1

Note: It is not possible to do an upscale of an image. When using a height parameter greater than the input image height, the Delivery API returns the image with its original height value.

Device pixel ratio (dpr)

Device pixel ratio is used to serve correctly sized images on different devices. The value represents the ratio between physical and logical pixels. For example, when a mobile device has a device pixel ratio of 2, there are twice as many physical pixels on the screen.

Dependencies: You must specify width, height, or both for this parameter to work.

The maximum supported device pixel ratio value is 5. When the value is higher than 5, the device pixel ratio is calculated as if the value was equal to 5.

Value
Description
Example

dpr

A floating-point number greater than 0 but less than 5.

Resize the width to 300px for screens with a device pixel ratio of 2. /on-roasts-1080px.jpg?w=300&dpr=2

Resize fit mode (fit)

The fit parameter controls how the output image is constrained within the provided size values after resizing. Valid values are clip, scale, and crop. The default value is clip.

Dependencies: You must specify width, height, or both for this parameter to work.

There are differences in how the resize fit modes change the aspect ratio. The aspect ratio of an image describes the proportional relationship between its width and its height.

When using the default clip mode, the image is resized to match one of the constraining dimensions. For example, attempting to resize the image of 300×200 (aspect ratio of 3:2) to be 100×100 will result in an image that is 100×67 because the aspect ratio of the original image is maintained.

When using the scale fit mode, the image is scaled and distorted to fit dimensions. When resizing the image to wider than the original, the image is scaled horizontally to fit dimensions. Similarly, when resizing the image to taller than the original, the image is scaled vertically to fit dimensions.

The crop fit mode crops the excess image data while keeping the image centered. This means that the center of the output image corresponds with the center of the input image.

Fit mode
Description
Aspect ratio
Example

clip

Default mode. Resizes the image to fit within the width and height boundaries without cropping or distorting the image.

The resulting image will match one of the constraining dimensions, while the other dimension is altered to maintain the same aspect ratio as the input image.

Attempting to resize the image to 600x500px with a fit mode of clip. /on-roasts-1080px.jpg?w=600&h=500&fit=clip

scale

Scales the image to fit the constraining dimensions exactly.

The resulting image will fill the dimensions, and will not maintain the aspect ratio of the input image.

Scale the image to 1200x150px, wider than the original. /on-roasts-1080px.jpg?w=1200&h=150&fit=scale

crop

Resizes the image to fill the width and height dimensions and crops any excess image data.

The resulting image will match the width and height constraints without distorting the image.

Crop the image to 300px in width and 150px in height. /on-roasts-1080px.jpg?w=300&h=150&fit=crop

Example: Resizing the original image coffe-cup.jpg to 300x100 using different resize fit modes.

Resize fit modes used to resize the image to 300x100.

Resize fit modes used to resize the image to 300x100.

Source rectangle region (rect)

By default, the entire image is used as the area for processing. The rect parameter selects a sub-region of the source image to use for processing before applying other resize operations.

Dependencies: The rect parameter is incompatible with the focal point crop method.

The value for rect is four relative values representing the starting coordinates of x and y and the width (w) and height (h), all separated by commas. All the values must be greater than or equal to 0.

If any of the values are represented by an integer greater than or equal to 1, they are interpreted in pixels. If the value is a float greater than 0 but less than 1, it's interpreted in percentages.

Values
Units
Description
Example

Integer

Pixels

A whole number between 1 and 8192.

Selecting a top-left region of the image for processing. /on-roasts-1080px.jpg?rect=1,1,700,466

Float

Percentage

A floating-point number greater than 0 but less than 1.

Selecting a top-left region of the image for processing. /on-roasts-1080px.jpg?rect=1,1,0.7,0.7

Example: Choosing a sub-region of the source image (604x403). Only the rectangle region of the image shown on the right will be used for processing.

Source rectangle region: `/coffee-cup.jpg?rect=115,230,0.4,0.4`

Source rectangle region: /coffee-cup.jpg?rect=115,230,0.4,0.4

Suggest Edits

Focal point crop

Choose the point of interest of your image when cropping the image.

 

Focal point crop allows you to intentionally art-direct a point of interest when cropping an image. As the image is then resized and cropped, the focal point determines which areas are centered and within bounds of the image, and what gets cropped out.

Dependencies: The focal point crop parameter must always be used with the fit=crop and crop=focalpoint parameters. Focal point crop is incompatible with the source rectangle region (rect) method.

Focal point crop consists of the horizontal (fp-x), vertical (fp-y), and zoom (fp-z) parameters.

To zoom-in on an image, the fp-z value needs to be greater than 1, with fp-z=1 representing the original size of the image. Every full step is then the equivalent of a 100% zoom, e.g., fp-z=2 is the same as viewing the image at 200%.

Focal point crop consists of the following parameters:

  • fp-x – The horizontal value of the focal point of an image. Must be a float between 0.0 and 1.0, inclusive. The default value is 0.5.
  • fp-y – The vertical value of the focal point of an image. Must be a float between 0.0 and 1.0, inclusive. The default value is 0.5.
  • fp-z – The zoom value of a focal point of an image. The default value is 1. The maximum value depends on the quality of the image, but we recommend using a float value between 1 and 100.

When the fp-x and fp-y values are not set, the Delivery API uses the default value of 0.5, which represents the center of the image. For example, /on-roasts-1080px.jpg?fit=crop&crop=focalpoint&fp-z=3 zooms-in on the center of the image by 300%.

Example: Choosing a focal point with the fp-x and fp-y values and then using a 200% zoom with the fp-z=2 results in the image on the right.

Focal point crop: `/coffee-cup.jpg?fit=crop&crop=focalpoint&fp-x=0.4&fp-y=0.8&fp-z=2`

Focal point crop: /coffee-cup.jpg?fit=crop&crop=focalpoint&fp-x=0.4&fp-y=0.8&fp-z=2

Suggest Edits

Format

Convert the image by choosing the output format and the quality of the compression.

 

Format parameter

The format (fm) parameter enables the source image to be converted from one encoded format to another. Valid values for the fm parameter are gif, png, png8, jpg, pjpg, and webp. For example, when converting a jpg image to a png format, the request would look like this: /on-roasts-1080px.jpg?fm=png.

The source image can be any of the following image formats: gif, png, jpeg, and webp.

Value
Description
Quality parameter

gif

Graphics Interchange Format

No

png

Portable Network Graphics

No

png8

Portable Network Graphics palette variant with 8-bit transparency and 256 colors

No

jpg

JPEG

Yes

pjpg

Progressive JPEG

Yes

webp

WebP

Yes

Quality parameter (jpg, pjpg, webp)

The quality (q) parameter enables control over the compression level for lossy file-formatted images (jpg, pjpg, webp). The value is an integer between 0 and 100. A lower number represents a lower-quality output image with a smaller file size and vice-versa. For example, /on-roasts-1080px.jpg?q=20 will lower the quality of the output image as well as its file size.

If no quality parameter is present, the output image will be returned with a default value of 85. Note that the quality parameter will be ignored by all output formats that are not lossy.

Dependencies: Quality parameter only works with the jpg, pjpg, and webp input image formats.

Lossless parameter (webp)

The lossless parameter enables delivery of lossless images in WebP format. Valid values are 1 and 0 or true and false. The default value is false, meaning a lossy compression. For example, /on-roasts-1080px.jpg?fm=webp&lossless=1 converts the JPEG image to WebP format via lossless compression.

When unset or set to an invalid value, lossless defaults to false.

Dependencies: Lossless parameter needs to be used with the fm parameter set to the WebP format.

Automatic format selection (webp)

Automatic delivery of WebP format images can be enabled by using the auto=format parameter. This will override the format parameter in browsers that support WebP.

If auto=format is set and the browser does not support the WebP format, the Delivery API will fall back to any format specified by the fm parameter, and finally the source image type. For example, the /on-roasts-1080px.jpg?fm=png&auto=format request will be evaluated as follows: If the web browser supports the WebP format, the image will be converted to webp. If the WebP format is not supported, the Delivery API will try to convert the image to png format. If this fails as well, the image will stay in its original format which is jpg.

Suggest Edits

List content items

Retrieve a list of content items in your project. By default, the content items are ordered alphabetically by codename.

 
gethttps://deliver.kenticocloud.com/project_id/items
curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/items?system.type=article&elements=title%2Csummary%2Cpost_date%2Cteaser_image&order=elements.post_date%5Bdesc%5D&depth=0&limit=3' \
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-net
DeliveryItemListingResponse<Article> response = await client.GetItemsAsync<Article>(
    new EqualsFilter("system.type", "article"),
    new ElementsParameter("title", "summary", "post_date", "teaser_image"),
    new ContainsFilter("elements.personas", "coffee_lover"),
    new OrderParameter("elements.post_date", SortOrder.Descending),
    new DepthFilter(0),
    new LimitParameter(3)
    );

var items = response.Items;
import { ContentItem, DeliveryClient, Fields, SortOrder, TypeResolver } from 'kentico-cloud-delivery';

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
export class Article extends ContentItem {
    public title: Fields.TextField;
    public summary: Fields.TextField;
    public post_date: Fields.DateTimeField;
    public teaser_image: Fields.AssetsField;
    public related_articles: Article[];
}

const deliveryClient = new DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    typeResolvers: [
        new TypeResolver('article', () => new Article)
    ]
});

deliveryClient.items<Article>()
    .type('article')
    .elementsParameter(['title', 'summary', 'post_date', 'teaser_image'])
    .orderParameter('elements.post_date', SortOrder.desc)
    .limitParameter(3)
    .depthParameter(0)
    .getObservable()
    .subscribe(response => console.log(response));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

List<NameValuePair> params = DeliveryParameterBuilder.params()
    .filterEquals("system.type", "article")
    .projection("title", "summary", "post_date", "teaser_image")
    .filterContains("elements.personas", "coffee_lover")
    .orderByDesc("elements.post_date")
    .modularContentDepth(0)
    .page(null, 3).build();

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-java
List<ArticleItem> items = client.getItems(ArticleItem.class, params);
const KenticoCloud = require('kentico-cloud-delivery');

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    typeResolvers: [
        new KenticoCloud.TypeResolver('article', () => new Article())
    ]
});

deliveryClient.items()
    .type('article')
    .elementsParameter(['title', 'summary', 'post_date', 'teaser_image'])
    .orderParameter('elements.post_date', KenticoCloud.SortOrder.desc)
    .limitParameter(3)
    .depthParameter(0)
    .getObservable()
    .subscribe(response => console.log(response));
import KenticoCloud
 
let client = DeliveryClient.init(projectId:"975bf280-fd91-488c-994c-2f04416e5ee3")
 
let customQuery = "items?system.type=article&elements=title,summary,post_date,teaser_image&order=elements.post_date[desc]&depth=0&limit=3"
client.getItems(modelType: Article.self, customQuery: customQuery) { (isSuccess, itemsResponse, error) in
      if isSuccess {
           if let articles = itemsResponse?.items {
               // Use your items here
           }
       } else {
           if let error = error {
               print(error)
           }
       }
import com.kenticocloud.delivery_core.*;
import com.kenticocloud.delivery_rx.*;

import io.reactivex.Observer;
import io.reactivex.disposables.Disposable;
import io.reactivex.functions.Function;

// Generate strongly-typed models via https://github.com/Kentico/cloud-generators-java
// Prepares an array to hold the 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";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId)
    .withTypeResolvers(typeResolvers);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets specific elements of 3 articles ordered by the "Post date" element using a simple request
List<Article> articles = deliveryService.<Article>items()
    .equalsFilter("system.type", "article")
    .elementsParameter(Arrays.asList("title", "summary", "post_date", "teaser_image"))
    .orderParameter("elements.post_date", OrderType.Desc)
    .limitParameter(3)
    .get()
    .getItems();

// Gets specific elements of 3 articles ordered by the "Post date" element using RxJava2
deliveryService.<Article>items()
    .equalsFilter("system.type", "article")
    .elementsParameter(Arrays.asList("title", "summary", "post_date", "teaser_image"))
    .orderParameter("elements.post_date", OrderType.Desc)
    .limitParameter(3)
    .getObservable()
    .subscribe(new Observer<DeliveryItemListingResponse<Article>>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryItemListingResponse<Article> response) {
            // Gets the mapped articles
            List<Article> articles = response.getItems();
        }

        @Override
        public void onError(Throwable e) {
        }

        @Override
        public void onComplete() {
        }
    });
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;
use KenticoCloud\Delivery\QueryParams;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$items = $client->getItems((new QueryParams())
            ->equals('system.type', 'article')
            ->elements(array('title', 'summary', 'post_date','teaser_image'))
            ->orderDesc('elements.post_date')
            ->limit(3)
            ->depth(0));
A binary file was returned

You couldn't be authenticated

{
  "items": [
    {
      "system": {
        "id": "cf106f4e-30a4-42ef-b313-b8ea3fd3e5c5",
        "name": "Coffee Beverages Explained",
        "codename": "coffee_beverages_explained",
        "language": "default",
        "type": "article",
        "sitemap_locations": [
          "articles"
        ],
        "last_modified": "2017-04-04T13:40:00.1102334Z"
      },
      "elements": {
        "title": {
          "type": "text",
          "name": "Title",
          "value": "Coffee Beverages Explained"
        },
        "summary": {
          "type": "text",
          "name": "Summary",
          "value": "Espresso and filtered coffee are the two main categories of coffee, based on the method of preparation. Learn about individual types of coffee that fall under these categories."
        },
        "post_date": {
          "type": "date_time",
          "name": "Post date",
          "value": "2014-11-18T00:00:00Z"
        },
        "teaser_image": {
          "type": "asset",
          "name": "Teaser image",
          "value": [
            {
              "name": "coffee-beverages-explained-1080px.jpg",
              "type": "image/jpeg",
              "size": 90895,
              "description": null,
              "url": "https://assets-us-01.kc-usercontent.com/975bf280-fd91-488c-994c-2f04416e5ee3/e700596b-03b0-4cee-ac5c-9212762c027a/coffee-beverages-explained-1080px.jpg"
            }
          ]
        }
      }
    },
    {
      "system": {
        "id": "23f71096-fa89-4f59-a3f9-970e970944ec",
        "name": "Donate with us",
        "codename": "donate_with_us",
        "language": "default",
        "type": "article",
        "sitemap_locations": [
          "articles"
        ],
        "last_modified": "2017-04-04T13:40:29.970377Z"
      },
      "elements": {
        "title": {
          "type": "text",
          "name": "Title",
          "value": "Donate with us"
        },
        "summary": {
          "type": "text",
          "name": "Summary",
          "value": "Dancing Goat regularly donates money to Children in Africa, a foundation helping children with food, accommodation, education, and other essentials. Donate with us and create a better world."
        },
        "post_date": {
          "type": "date_time",
          "name": "Post date",
          "value": "2014-11-12T00:00:00Z"
        },
        "teaser_image": {
          "type": "asset",
          "name": "Teaser image",
          "value": [
            {
              "name": "donate-with-us-1080px.jpg",
              "type": "image/jpeg",
              "size": 133239,
              "description": null,
              "url": "https://assets-us-01.kc-usercontent.com/975bf280-fd91-488c-994c-2f04416e5ee3/9b86141d-b667-4c35-82b1-826bc151d72a/donate-with-us-1080px.jpg"
            }
          ]
        }
      }
    },
    {
      "system": {
        "id": "b2fea94c-73fd-42ec-a22f-f409878de187",
        "name": "Origins of Arabica Bourbon",
        "codename": "origins_of_arabica_bourbon",
        "language": "default",
        "type": "article",
        "sitemap_locations": [
          "articles"
        ],
        "last_modified": "2017-04-04T13:45:44.1533096Z"
      },
      "elements": {
        "title": {
          "type": "text",
          "name": "Title",
          "value": "Origins of Arabica Bourbon"
        },
        "summary": {
          "type": "text",
          "name": "Summary",
          "value": "This one particular type of coffee, the Arabica Bourbon, is now sold only in Japan. It has been brought back to life by enthusiasts after being almost forgotten for nearly sixty years."
        },
        "post_date": {
          "type": "date_time",
          "name": "Post date",
          "value": "2014-11-11T00:00:00Z"
        },
        "teaser_image": {
          "type": "asset",
          "name": "Teaser image",
          "value": [
            {
              "name": "origins-of-arabica-bourbon-1080px.jpg",
              "type": "image/jpeg",
              "size": 132229,
              "description": null,
              "url": "https://assets.kenticocloud.com:443/975bf280-fd91-488c-994c-2f04416e5ee3/1cfcb6c9-1fe6-4013-a0bb-b26f8ada2ebf/origins-of-arabica-bourbon-1080px.jpg"
            }
          ]
        }
      }
    }
  ],
  "modular_content": {},
  "pagination": {
    "skip": 0,
    "limit": 3,
    "count": 3,
    "next_page": "https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/items?system.type=article&elements=title%2csummary%2cpost_date%2cteaser_image&order=elements.post_date%5bdesc%5d&depth=0&limit=3&skip=3"
  }
}
{
  "items": [],
  "modular_content": {},
  "pagination": {
    "skip": 0,
    "limit": 0,
    "count": 0,
    "next_page": ""
  }
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

Query Params

language
string

Determines which language variant of content to return. By default, the API returns content in the default project 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: en-US.

elements
string

A comma-separated list of content type element codenames. Use this parameter to choose which elements to retrieve. If not specified, all elements are retrieved. See Projection. Example: title,summary,post_date,teaser_image.

order
string

Order of the retrieved content items. By default, the items are sorted alphabetically by their codenames from A to Z in descending order. Example: elements.post_date[desc].

depth
int32

Content items can use Linked items and Rich text elements to reference other content items. By default, only the first level of linked items is returned. If you need to exclude all linked items from the response, set the parameter to 0. Components are always present in response. See Linked content and components for more details.

skip
int32

Number of content items to skip. Example: 10.

limit
int32

Number of content items to retrieve in a single request. Example: 10. If the limit is lower than the total number of items matching your query, the next_page attribute in the Pagination object will contain a URL to the next page of results.

Headers

X-KC-Wait-For-Loading-New-Content
string

If the requested content has changed since the last request, the header determines whether to wait while fetching content. This can be useful when retrieving changed content in reaction to a webhook call. By default, when the header is not set, the API serves old content (if cached by the CDN) while it's fetching the new content to minimize wait time. To always fetch new content, set the header value to true.

 

Returns

A listing response object with a collection of content items. If your query does not match any content items, the API returns a standard listing response with empty items and modular_content (linked content) attributes.

To learn how you can filter the listing response by individual attributes, see Filtering retrieved content.

Suggest Edits

Content item model

Object model description of a single content item object.

 

When retrieving a single content item, the Delivery API returns a content item object with the following attributes:

Attribute Description Type Notes
item Content item data collection of the system and elements attributes
system System attributes of the content item System object
elements Content type elements in the content item collection of Element objects The order of the Element objects might not match the order in the UI.
modular_content A list of components and content items used in Linked items and Rich text elements collection of Content item objects The Content item objects (including component objects) are returned in no particular order and cannot be filtered. See Linked content for more details.

Every content item in a JSON response from the Delivery API contains a system attribute. This attribute represents the System object with information about the retrieved content item.

System object (content item)

Attribute Description Type Notes
id Unique identifier of the content item string
name Display name of the content item string
codename Codename of the content item string Generated from the content item's display name.
language Codename of the language variant string For details on retrieving content in different languages, see Localization.
type Codename of the content type string
sitemap_locations A list of sitemap locations the content item is in array of strings
last_modified When was the content item last modified string ISO-8601 formatted date/time.

Example: Content item object

{
  "item": {
    "system": {
      "id": "cf106f4e-30a4-42ef-b313-b8ea3fd3e5c5",
      "name": "Coffee Beverages Explained",
      "codename": "coffee_beverages_explained",
      "language": "en-US",
      "type": "article",
      "sitemap_locations": [
        "articles"
      ],
      "last_modified": "2016-10-27T11:14:58.9229067Z"
    },
    "elements": {
      # collection of Element objects
    }
  },
  "modular_content": {
    # collection of Content item objects (including component objects)
  }
}
Suggest Edits

View a content item

Retrieve a specific content item by specifying its codename.

 
gethttps://deliver.kenticocloud.com/project_id/items/content_item_codename
curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/items/on_roasts?elements=title%2Csummary%2Cpost_date%2Cteaser_image%2Crelated_articles' \
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-net
DeliveryItemResponse<Article> response = await client.GetItemAsync<Article>("on_roasts",
    new ElementsParameter("title", "summary", "post_date", "teaser_image", "related_articles")
    );

ContentItem item = response.Item;
import { ContentItem, DeliveryClient, Fields, TypeResolver, SortOrder } from 'kentico-cloud-delivery';

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
export class Article extends ContentItem {
    public title: Fields.TextField;
    public summary: Fields.TextField;
    public post_date: Fields.DateTimeField;
    public teaser_image: Fields.AssetsField;
    public related_articles: Article[];
}

const deliveryClient = new DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    typeResolvers: [
      new TypeResolver('article', () => new Article)
    ]
});

deliveryClient.item<Article>('on_roasts')
    .elementsParameter(['title', 'summary', 'post_date', 'teaser_image'])
    .getObservable()
    .subscribe(response => console.log(response.item));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

List<NameValuePair> params = DeliveryParameterBuilder.params().projection("title", "summary", "post_date", "teaser_image", "related_articles").build();

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-java
ArticleItem item = client.getItem("on_roasts", ArticleItem.class, params);
const KenticoCloud = require('kentico-cloud-delivery');

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    typeResolvers: [
        new KenticoCloud.TypeResolver('article', () => new Article())
    ]
});

deliveryClient.item('on_roasts')
    .elementsParameter(['title', 'summary', 'post_date', 'teaser_image'])
    .getObservable()
    .subscribe(response => console.log(response.item));
import KenticoCloud

let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")

client.getItem(modelType: Article.self, itemName: "on_roasts") { (isSuccess, deliveryItem, error) in
     if isSuccess {
        if let article = deliveryItem.item {
            // Use your item here
        }
    } else {
        if let error = error {
            print(error)
        }
    }
import com.kenticocloud.delivery_core.*;
import com.kenticocloud.delivery_rx.*;

import io.reactivex.Observer;
import io.reactivex.disposables.Disposable;
import io.reactivex.functions.Function;

// Generate strongly-typed models via https://github.com/Kentico/cloud-generators-java
// Prepares an array to hold the 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";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId)
  .withTypeResolvers(typeResolvers);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets specific elements of an article using a simple request
Article article = deliveryService.<Article>item("on_roasts")
    .elementsParameter(Arrays.asList("title", "summary", "post_date", "teaser_image"))
    .get()
    .getItem();

// Gets specific elements of an article using RxJava2
deliveryService.<Article>item("on_roasts")
    .elementsParameter(Arrays.asList("title", "summary", "post_date", "teaser_image"))
    .getObservable()
    .subscribe(new Observer<DeliveryItemResponse<Article>>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryItemResponse<Article> response) {
            // Gets the article
            Article article = response.getItem();
        }

        @Override
        public void onError(Throwable e) {
        }

        @Override
        public void onComplete() {
        }
    });
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$item = $client->getItem('on_roasts', (new QueryParams())
            ->elements(array('title', 'summary', 'post_date','teaser_image', 'related_articles')));
A binary file was returned

You couldn't be authenticated

{
  "item": {
    "system": {
      "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474",
      "name": "On Roasts",
      "codename": "on_roasts",
      "language": "default",
      "type": "article",
      "sitemap_locations": [
        "articles"
      ],
      "last_modified": "2016-10-20T12:03:48.4628352Z"
    },
    "elements": {
      "title": {
        "type": "text",
        "name": "Title",
        "value": "On Roasts"
      },
      "summary": {
        "type": "text",
        "name": "Summary",
        "value": "Roasting coffee beans can take from 6 to 13 minutes. Different roasting times produce different types of coffee, with varying concentration of caffeine and intensity of the original flavor."
      },
      "post_date": {
        "type": "date_time",
        "name": "Post date",
        "value": "2014-11-07T00:00:00Z"
      },
      "teaser_image": {
        "type": "asset",
        "name": "Teaser image",
        "value": [
          {
            "name": "on-roasts-1080px.jpg",
            "type": "image/jpeg",
            "size": 0,
            "description": null,
            "url": "https://assets-us-01.kc-usercontent.com/5859c8b2-f64d-405f-a306-d65dd5b1da04/f6daed1f-3f3b-4036-a9c7-9519359b9601/on-roasts-1080px.jpg"
          }
        ]
      },
      "related_articles": {
        "type": "modular_content",
        "name": "Related articles",
        "value": [
          "coffee_processing_techniques",
          "origins_of_arabica_bourbon"
        ]
      }
    }
  },
  "modular_content": {
    # collection of related Content item objects (including component objects)
  }
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_item_codename
string
required

The codename of a specific content item. Example: on_roasts.

Query Params

language
string

Determines which language variant of content to return. By default, the API returns content in the default project 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: en-US.

elements
string

A comma-separated list of content type element codenames. Use this parameter to choose which elements to retrieve. If not specified, all elements are retrieved. See Projection. Example: title,summary,post_date,teaser_image.

depth
int32

Content items can use Linked items and Rich text elements to reference other content items. By default, only the first level of linked items is returned. If you need to exclude all linked items from the response, set the parameter to 0. Components are always present in response. See Linked content and components for more details.

Headers

X-KC-Wait-For-Loading-New-Content
string

If the requested content has changed since the last request, the header determines whether to wait while fetching content. This can be useful when retrieving changed content in reaction to a webhook call. By default, when the header is not set, the API serves old content (if cached by the CDN) while it's fetching the new content to minimize wait time. To always fetch new content, set the header value to true.

 

Returns

A single Content item object if a valid content item codename was specified. When requesting the codename of a content item that is not published or was deleted, the API returns an error response with a 404 HTTP status code.

Suggest Edits

List content types

Retrieve a list of content types in your project.

 
gethttps://deliver.kenticocloud.com/project_id/types
curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/types?limit=3' \
  --header 'content-type: application/json'
using KenticoCloud.Delivery;
 
DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");
 
DeliveryTypeListingResponse response = await client.GetTypesAsync(
    new LimitParameter(3)
    );
 
var types = response.Types;
import { DeliveryClient } from 'kentico-cloud-delivery';

const deliveryClient = new DeliveryClient({
  projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.types()
  .limitParameter(3)
  .getObservable()
  .subscribe(response => console.log(response.types));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

List<NameValuePair> params = DeliveryParameterBuilder.params().page(null, 3).build();
ContentTypesListingResponse types = client.getTypes(params);
const KenticoCloud = require('kentico-cloud-delivery');

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.types()
    .limitParameter(3)
    .getObservable()
    .subscribe(response => console.log(response.types));
import KenticoCloud
 
let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")
 
client.getContentTypes(limit: 3, completionHandler: { (isSuccess, contentTypesResponse, error) in
    if !isSuccess {
        fail( "Response is not successful. Error: \(String(describing: error))" )
    }
     
    if let response = contentTypesResponse {
    // use content types here
    }
})
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 the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets 3 content types using a simple request
List<ContentType> types = deliveryService.types()
    .limitParameter(3)
    .get()
    .getTypes();

// Gets 3 content types using RxJava2
deliveryService.types()
    .limitParameter(3)
    .getObservable()
    .subscribe(new Observer<DeliveryTypeListingResponse>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryTypeListingResponse response) {
            // Gets content types from response
            List<ContentType> types = response.getTypes();
        }

        @Override
        public void onError(Throwable e) {
        }

        @Override
        public void onComplete() {
        }
    });
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;
use KenticoCloud\Delivery\QueryParams;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$types = $client->getTypes((new QueryParams())
            ->limit(3));
A binary file was returned

You couldn't be authenticated

{
  "types": [
    {
      "system": {
        "id": "b2c14f2c-6467-460b-a70b-bca17972a33a",
        "name": "About us",
        "codename": "about_us",
        "last_modified": "2017-08-02T07:33:28.2997578Z"
      },
      "elements": {
        "facts": {
          "type": "modular_content",
          "name": "Facts"
        },
        "url_pattern": {
          "type": "url_slug",
          "name": "URL pattern"
        }
      }
    },
    {
      "system": {
        "id": "d9748663-f567-4c51-a922-c24a1d6b935a",
        "name": "Accessory",
        "codename": "accessory",
        "last_modified": "2017-08-02T07:33:39.3620325Z"
      },
      "elements": {
        "product_name": {
          "type": "text",
          "name": "Product name"
        },
        "price": {
          "type": "number",
          "name": "Price"
        },
        "image": {
          "type": "asset",
          "name": "Image"
        },
        "manufacturer": {
          "type": "text",
          "name": "Manufacturer"
        },
        "product_status": {
          "type": "taxonomy",
          "name": "Product status",
          "taxonomy_group": "product_status"
        },
        "short_description": {
          "type": "rich_text",
          "name": "Short description"
        },
        "long_description": {
          "type": "rich_text",
          "name": "Long description"
        },
        "url_pattern": {
          "type": "url_slug",
          "name": "URL pattern"
        }
      }
    },
    {
      "system": {
        "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89",
        "name": "Article",
        "codename": "article",
        "last_modified": "2017-08-02T07:33:19.8599559Z"
      },
      "elements": {
        "personas": {
          "type": "taxonomy",
          "name": "Personas",
          "taxonomy_group": "personas"
        },
        "title": {
          "type": "text",
          "name": "Title"
        },
        "teaser_image": {
          "type": "asset",
          "name": "Teaser image"
        },
        "post_date": {
          "type": "date_time",
          "name": "Post date"
        },
        "summary": {
          "type": "text",
          "name": "Summary"
        },
        "body_copy": {
          "type": "rich_text",
          "name": "Body Copy"
        },
        "related_articles": {
          "type": "modular_content",
          "name": "Related articles"
        },
        "meta_keywords": {
          "type": "text",
          "name": "Meta keywords"
        },
        "meta_description": {
          "type": "text",
          "name": "Meta description"
        },
        "url_pattern": {
          "type": "url_slug",
          "name": "URL pattern"
        }
      }
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 3,
    "count": 3,
    "next_page": "https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/types?limit=3&skip=3"
  }
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

Query Params

skip
int32

Number of content types to skip from the response. Example: 10.

limit
int32

Number of content items to retrieve in a single request. Example: 10. If the limit is lower than the total number of items matching your query, the next_page attribute in the Pagination object will contain a URL to the next page of results.

Headers

X-KC-Wait-For-Loading-New-Content
string

If the requested content has changed since the last request, the header determines whether to wait while fetching content. This can be useful when retrieving changed content in reaction to a webhook call. By default, when the header is not set, the API serves old content (if cached by the CDN) while it's fetching the new content to minimize wait time. To always fetch new content, set the header value to true.

 

Returns

A listing response object with a collection of content types in your project.

Suggest Edits

Content type model

Object model description of a single content type object.

 

When retrieving a single content type, the Delivery API returns a content type object with the following attributes:

Attribute Description Type Notes
system System attributes of the content type System object
elements Content type elements in the content item collection of Element objects The order of the Element objects might not match the order in the UI.

Every content type in a JSON response from the Delivery API contains a system attribute. This attribute represents the System object with information about the retrieved content type.

System object (content type)

Attribute Description Type Notes
id Unique identifier of the content item string
name Display name of the content item string
codename Codename of the content item string Generated from the content item's display name.
last_modified When was the content item last modified string ISO-8601 formatted date/time.

Example: Content type object

{
  "system": {
    "id": "b2c14f2c-6467-460b-a70b-bca17972a33a",
    "name": "About us",
    "codename": "about_us",
    "last_modified": "2016-10-20T12:03:17.4685693Z"
  },
  "elements": {
    # collection of Element objects
  }
}
Suggest Edits

View a content type

Retrieve a specific content type from your project by specifying its codename.

 
gethttps://deliver.kenticocloud.com/project_id/types/content_type_codename
curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/types/coffee' \
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

ContentType type = await client.GetTypeAsync("coffee");
import { DeliveryClient } from 'kentico-cloud-delivery';

const deliveryClient = new DeliveryClient({
  projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.type('coffee')
    .getObservable()
    .subscribe(response => console.log(response.type));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

ContentType type = client.getType("coffee");
const KenticoCloud = require('kentico-cloud-delivery');

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.type('coffee')
    .getObservable()
    .subscribe(response => console.log(response.type));
import KenticoCloud
 
let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")
 
client.getContentType(name: "coffee", completionHandler: { (isSuccess, contentType, error) in
    if !isSuccess {
        fail( "Response is not successful. Error: \(String(describing: error))" )
    }
     
    if let type = contentType {
    // use content type here
    }
})
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 the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets a content type using a simple request
ContentType type = deliveryService.type("coffee")
    .get()
    .getType();

// Gets a content type using RxJava2
deliveryService.type("coffee")
    .getObservable()
    .subscribe(new Observer<DeliveryTypeResponse>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryTypeResponse response) {
            // Gets the type from response
            ContentType type = response.getType();
        }

        @Override
        public void onError(Throwable e) {
        }

        @Override
        public void onComplete() {
        }
    });
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$type = $client->getType('coffee');
A binary file was returned

You couldn't be authenticated

{
  "system": {
    "id": "929985ac-4aa5-436b-85a2-94c2d4fbbebd",
    "name": "Coffee",
    "codename": "coffee",
    "last_modified": "2017-02-02T14:58:53.5809087Z"
  },
  "elements": {
    "product_name": {
      "type": "text",
      "name": "Product name"
    },
    "price": {
      "type": "number",
      "name": "Price"
    },
    "image": {
      "type": "asset",
      "name": "Image"
    },
    "short_description": {
      "type": "rich_text",
      "name": "Short description"
    },
    "long_description": {
      "type": "rich_text",
      "name": "Long description"
    },
    "product_status": {
      "type": "taxonomy",
      "name": "Product status",
      "taxonomy_group": "product_status"
    },
    "farm": {
      "type": "text",
      "name": "Farm"
    },
    "country": {
      "type": "text",
      "name": "Country"
    },
    "variety": {
      "type": "text",
      "name": "Variety"
    },
    "processing": {
      "type": "multiple_choice",
      "name": "Processing",
      "options": [
        {
          "name": "Semi-dry",
          "codename": "semi_dry"
        },
        {
          "name": "Wet (Washed)",
          "codename": "wet__washed_"
        },
        {
          "name": "Dry (Natural)",
          "codename": "dry__natural_"
        }
      ]
    },
    "altitude": {
      "type": "text",
      "name": "Altitude"
    }
  }
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_type_codename
string
required

The codename of a specific content type. Example: coffee.

Headers

X-KC-Wait-For-Loading-New-Content
string

If the requested content has changed since the last request, the header determines whether to wait while fetching content. This can be useful when retrieving changed content in reaction to a webhook call. By default, when the header is not set, the API serves old content (if cached by the CDN) while it's fetching the new content to minimize wait time. To always fetch new content, set the header value to true.

 

Returns

A single Content type object if a valid content type codename was specified. If your query does not match any content type, the API returns an error response with a 404 HTTP status code.

Suggest Edits

Content element model

Object model descriptions of individual content elements.

 

When retrieving content items or content types, you get an elements collection as a part of the retrieved item or type.

Element object

Each element in the elements collection contains the following attributes:

Attribute Description Type Notes
type Type of the element string Valid values: text, rich_text, number, multiple_choice, date_time, asset, modular_content (Linked items element), taxonomy, url_slug.
name Display name of the element string
value Value of the element varies Data type is based on the type of the element – see examples below for more details.

Note that certain elements, such as Rich text or Taxonomy, can contain additional attributes.

For an overview of the available elements and their limits, see the reference of content type elements in our Help Center.

Text element

The value of a Text element is a string.

"meta_keywords": {
  "type": "text",
  "name": "Meta keywords",
  "value": "\"coffee beginner\", beverages"
}
"meta_keywords": {
  "type": "text",
  "name": "Meta keywords"
}

Rich text element

Besides formatted text, the Rich text element's value attribute can contain objects representing images, components, content items, and links to content items. Information about these objects is stored in the images, modular_content (components and items), and links attributes.

"description": {
  "type": "rich_text",
  "name": "Description",
  "images": {
    "14mio": {
      "image_id": "14mio",
      "description": "Roasting coffee beans",
      "url": "https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/roaster.jpg"
    }
  },
  "links": {
    "f4b3fc05-e988-4dae-9ac1-a94aba566474": {
      "type": "article",
      "codename": "on_roasts",
      "url_slug": ""
    }
  },
  "modular_content": [
    "coffee_processing_techniques", # content item in Rich text
    "n249afaaf_1de5_011f_f683_c78fd9ec9d7c" # component in Rich text
  ],
  "value": "<p>We operate our own roasteries, one on every continent we cover, from where we distribute right to the shops. This allows you to experience every cup as if you were right at the very farm it originated from. To achieve this, we use a refurbished 1920s Probat coffee roasters.</p>\n<figure data-image-id=\"14mio\"><img src=\"https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/roaster.jpg\" alt=\"Roasting coffee beans\" data-image-id=\"14mio\"></figure><p>We know that roasting is something you must keep on constantly perfecting. <object type=\"application/kenticocloud\" data-type=\"item\" data-rel=\"component\" data-codename=\"n249afaaf_1de5_011f_f683_c78fd9ec9d7c\"></object> Each coffee requires a different roast to get the aroma and taste just right. That’s why our experts fine tune the way we <a data-item-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\" href=\"\">roast coffees</a> every day. It’s a constant struggle.</p><object type=\"application/kenticocloud\" data-type=\"item\" data-codename=\"coffee_processing_techniques\"></object>"
}
"description": {
  "type": "rich_text",
  "name": "Description"
}

Images (single object)

Each object in the images collection represents an image id, e.g., 14mio.

Attribute Description Type Notes
image_id ID of the image string
description Description of the image string Used for the alt attribute of an <img> tag.
url Absolute URL for the image string

In the value attribute of the Rich text element, images are represented by figure and img tags:

<figure data-image-id=\"14mio\"><img src=\"https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/237362b4-5f2b-480e-a1d3-0ad5a6d5f8bd/roaster.jpg\" alt=\"Roasting coffee beans\" data-image-id=\"14mio\"></figure>

Modular content (components and items in rich text)

The modular_content collection represents components and content items inserted into rich text. The list is represented as an array of strings, each string being a data-codename of a content item or component. The contents of the items and components can be found in the modular_content attribute of the entire Content item model.

In the value attribute of the Rich text element, content items and components are represented by object tags:

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

<!--component-->
<object type="application/kenticocloud\" data-type="item" data-rel="component" data-codename="n249afaaf_1de5_011f_f683_c78fd9ec9d7c"></object>

Note that both components and items have a data-type="item" attribute so they can be resolved using a single method. You can still differentiate between items and components in Rich text using the data-rel attribute.

Links (single object)

Each object in the links collection represents a content item ID in the GUID format, e.g., f4b3fc05-e988-4dae-9ac1-a94aba566474.

Attribute Description Type Notes
type Content type of the content item string
codename Display name of the element string
url_slug URL slug of the content item string Empty string if the content item's type does not use a URL slug element.

In the value attribute of the Rich text element, links are represented by a tags:

<a data-item-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\" href=\"\">roast coffees</a>

Multiple choice element

The value of a Multiple choice element is an array of option objects. Each option object has a name and codename. The order of the option objects in the array matches the order of the options in the UI.

"processing": {
  "type": "multiple_choice",
  "name": "Processing",
  "value": [
    {
      "name": "Dry (Natural)",
      "codename": "dry__natural_"
    }
  ]
}
"processing": {
  "type": "multiple_choice",
  "name": "Processing",
  "options": [
    {
      "name": "Dry (Natural)",
      "codename": "dry__natural_"
    },
    {
      "name": "Wet (Washed)",
      "codename": "wet__washed_"
    },
    {
      "name": "Semi-dry",
      "codename": "semi_dry"
    }
  ]
}

Number element

The value of a Number element is a decimal number. If empty, the value is null.

"price": {
  "type": "number",
  "name": "Price",
  "value": 8.5
}
"price": {
  "type": "number",
  "name": "Price"
}

Date & time element

The value of a Date & time element is an ISO-8601 formatted string. If empty, the value is null.

"post_date": {
  "type": "date_time",
  "name": "Post date",
  "value": "2014-11-18T00:00:00Z"
}
"post_date": {
  "type": "date_time",
  "name": "Post date"
}

Asset element

When used in content items, Asset elements can contain multiple assets. The value in the JSON response for an Asset element consists of an array of asset objects. The objects are returned in the same order as shown in the UI.

Asset object

Attribute Description Type
name File name of the asset string
type MIME type of the asset string
size Size of the asset in bytes integer
description Description of the asset string
url Absolute URL for the asset string
"teaser_image": {
  "type": "asset",
  "name": "Teaser image",
  "value": [
    {
      "name": "coffee-beverages-explained-1080px.jpg",
      "type": "image/jpeg",
      "size": "90895",
      "description": null,
      "url": "https://assets-us-01.kc-usercontent.com/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/e700596b-03b0-4cee-ac5c-9212762c027a/coffee-beverages-explained-1080px.jpg"
    }
  ]
}
"teaser_image": {
  "type": "asset",
  "name": "Teaser image"
}

Linked items element (formerly called Modular content)

The relations to content items saved in a Linked items element are represented as an array of strings. Each string being a codename of a content item. The order of 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 attribute of the Content item model.

"facts": {
  "type": "modular_content",
  "name": "Facts",
  "value": [
    "our_philosophy",
    "how_we_source_our_coffees",
    "how_we_roast_our_coffees"
  ]
}
"facts": {
  "type": "modular_content",
  "name": "Facts"
}

Taxonomy

The value of Taxonomy elements is an array of taxonomy item objects.

"personas": {
  "type": "taxonomy",
  "name": "Personas",
  "taxonomy_group": "personas",
  "value": [
    {
      "name": "Coffee lover",
      "codename": "coffee_lover"
    }
  ]
}
"personas": {
  "type": "taxonomy",
  "name": "Personas",
  "taxonomy_group": "personas"
}

URL slug

The value of URL slug elements is a string.

"url_slug": {
  "type": "url_slug",
  "name": "URL slug",
  "value": "brazil-natural-barra-grande"
}
"url_slug": {
  "type": "url_slug",
  "name": "URL slug"
}

Content type snippet

Content type snippet elements are expanded into the elements they contain. You can recognize expanded elements by their codenames.

For example, a snippet with 2 elements will be structured as the 2 elements, without any encapsulation. Such 2 elements will have codenames in the following format: <content_type_snippet_codename>__<content_element_codename>.

"seo_metatata__meta_keywords": {
  "type": "text",
  "name": "Meta keywords",
  "value": "donation, africa"
},
"seo_metatata__meta_description": {
  "type": "text",
  "name": "Meta description",
  "value": "Dancing Goat regularly donates money to Children in Africa, a foundation helping children with food, accommodation, education, and other essentials."
}
"seo_metatata__meta_keywords": {
  "type": "text",
  "name": "Meta keywords"
},
"seo_metatata__meta_description": {
  "type": "text",
  "name": "Meta description"
}
Suggest Edits

View a content type element

Retrieve a specific content type element by specifying its codename and its parent content type.

 
gethttps://deliver.kenticocloud.com/project_id/types/content_type_codename/elements/element_codename
curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/types/coffee/elements/processing' \
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

ContentElement element = await client.GetContentElementAsync("coffee", "processing");
import { DeliveryClient } from 'kentico-cloud-delivery';

const deliveryClient = new DeliveryClient({
  projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.element('coffee', 'processing')
    .getObservable()
    .subscribe(response => console.log(response));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

Element element = client.getContentTypeElement("coffee", "processing");
const KenticoCloud = require('kentico-cloud-delivery');

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.element('coffee', 'processing')
    .getObservable()
    .subscribe(response => console.log(response));
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 the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets the "Processing" content element from the "Coffee" type using a simple request
ContentTypeElement element = deliveryService.contenTypeElement("coffee", "processing")
    .get()
    .getElement();

// Gets the "Processing" content element from the "Coffee" type using RxJava2
deliveryService.contenTypeElement("coffee", "processing")
    .getObservable()
    .subscribe(new Observer<DeliveryContentTypeElementResponse>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryContentTypeElementResponse response) {
            // Gets the content element
            ContentTypeElement element = response.getElement();
        }

        @Override
        public void onError(Throwable e) {
        }

        @Override
        public void onComplete() {
        }
    });
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$element = $client->getElement('coffee', 'processing');
A binary file was returned

You couldn't be authenticated

{
  "type": "taxonomy",
  "name": "Processing",
  "taxonomy_group": "processing",
  "codename": "processing"
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_type_codename
string
required

The codename of a specific content type. Example: coffee.

element_codename
string
required

The codename of a specific element in the selected content type. Note that the element's codename has no relation to the type of the element. Example: processing.

Headers

X-KC-Wait-For-Loading-New-Content
string

If the requested content has changed since the last request, the header determines whether to wait while fetching content. This can be useful when retrieving changed content in reaction to a webhook call. By default, when the header is not set, the API serves old content (if cached by the CDN) while it's fetching the new content to minimize wait time. To always fetch new content, set the header value to true.

 

Returns

A single content type Element object. If your query does not match any element in the selected content type, the API returns an error response with a 404 HTTP status code.

Suggest Edits

List taxonomy groups

Retrieve a paginated list of taxonomy groups in your project. By default, the API returns all taxonomy groups ordered alphabetically by codename, but pagination can be customized (see the endpoint parameter details below).

 
gethttps://deliver.kenticocloud.com/project_id/taxonomies
curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/taxonomies?limit=3' \
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

DeliveryTypeListingResponse response = await client.GetTaxonomiesAsync(
    new LimitParameter(3)
    );

var taxonomyGroups = response.Taxonomy;
import { DeliveryClient } from 'kentico-cloud-delivery';

const deliveryClient = new DeliveryClient({
  projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.taxonomies()
    .limitParameter(3)
    .getObservable()
    .subscribe(response => console.log(response.taxonomies));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

List<NameValuePair> params = DeliveryParameterBuilder.params().page(null, 3).build();

TaxonomyGroupListingResponse response = client.getTaxonomyGroups(params);
const KenticoCloud = require('kentico-cloud-delivery');

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.taxonomies()
    .limitParameter(3)
    .getObservable()
    .subscribe(response => console.log(response.taxonomies));
import KenticoCloud

let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")

client.getTaxonomies(completionHandler: { (isSuccess, deliveryItems, error) in
   if isSuccess {
       if let taxonomies = deliveryItems?.items {
        // use your taxonomies here
       }
    } else {
         if let error = error {
             print(error)
         }
    }
})
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 the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets 3 taxonomy groups using a simple request
List<Taxonomy> taxonomies = deliveryService.taxonomies()
    .limitParameter(3)
    .get()
    .getTaxonomies();

// Gets 3 taxonomy groups using RxJava2
deliveryService.taxonomies()
    .limitParameter(3)
    .getObservable()
    .subscribe(new Observer<DeliveryTaxonomyListingResponse>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryTaxonomyListingResponse response) {
            // Gets the taxonomy groups
            List<Taxonomy> taxonomies = response.getTaxonomies();
        }

        @Override
        public void onError(Throwable e) {
        }

        @Override
        public void onComplete() {
        }
    });
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;
use KenticoCloud\Delivery\QueryParams;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$taxonomyGroups = $client->getTaxonomies((new QueryParams())
            ->limit(3));
A binary file was returned

You couldn't be authenticated

{
  "taxonomies": [
    {
      "system": {
        "id": "f30c7f72-e9ab-8832-2a57-62944a038809",
        "name": "Personas",
        "codename": "personas",
        "last_modified": "2016-10-20T13:24:00.3200182Z"
      },
      "terms": [
        {
          "name": "Coffee expert",
          "codename": "coffee_expert",
          "terms": [
            {
              "name": "Barista",
              "codename": "barista",
              "terms": []
            },
            {
              "name": "Cafe owner",
              "codename": "cafe_owner",
              "terms": []
            }
          ]
        },
        {
          "name": "Coffee enthusiast",
          "codename": "coffee_enthusiast",
          "terms": [
            {
              "name": "Coffee lover",
              "codename": "coffee_lover",
              "terms": []
            },
            {
              "name": "Coffee blogger",
              "codename": "coffee_blogger",
              "terms": []
            }
          ]
        }
      ]
    },
    {
      "system": {
        "id": "d351400e-0290-87b2-1413-6c411d8ae5a4",
        "name": "Processing type",
        "codename": "processing_type",
        "last_modified": "2017-09-04T12:50:20.7857817Z"
      },
      "terms": [
        {
          "name": "Wet (Washed)",
          "codename": "wet__washed_",
          "terms": []
        },
        {
          "name": "Dry (Natural)",
          "codename": "dry__natural_",
          "terms": []
        },
        {
          "name": "Semi-dry",
          "codename": "semi_dry",
          "terms": []
        }
      ]
    },
    {
      "system": {
        "id": "79b1c5b6-30bc-d076-a236-d9ec9f1ff01b",
        "name": "Product status",
        "codename": "product_status",
        "last_modified": "2016-09-15T10:53:25.2233101Z"
      },
      "terms": [
        {
          "name": "On sale",
          "codename": "on_sale",
          "terms": []
        },
        {
          "name": "Bestseller",
          "codename": "bestseller",
          "terms": []
        }
      ]
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 3,
    "count": 3,
    "next_page": ""
  }
}
{
  "taxonomies": [],
  "pagination": {
    "skip": 0,
    "limit": 3,
    "count": 0,
    "next_page": ""
  }
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

Query Params

skip
int32

Number of taxonomy groups to skip. Example: 10.

limit
int32

Number of taxonomy groups to retrieve in a single request. Example: 10. If the limit is lower than the total number of groups matching your query, the next_page attribute in the Pagination object will contain a URL to the next page of results.

Headers

X-KC-Wait-For-Loading-New-Content
string

If the requested content has changed since the last request, the header determines whether to wait while fetching content. This can be useful when retrieving changed content in reaction to a webhook call. By default, when the header is not set, the API serves old content (if cached by the CDN) while it's fetching the new content to minimize wait time. To always fetch new content, set the header value to true.

 

Returns

A listing response object with a collection of taxonomy groups. If your query does not match any taxonomy groups, the API returns a standard listing response with an empty taxonomies attribute.

Suggest Edits

Taxonomy group model

Object model description of a single taxonomy group object.

 

When retrieving a single taxonomy group, the Delivery API returns a taxonomy group object with the following attributes:

Attribute Description Type
system System attributes of the taxonomy group System
terms taxonomy terms in the taxonomy group collection of Term objects

Every taxonomy group in a JSON response from the Delivery API contains a system attribute. This attribute represents the System object with information about the retrieved taxonomy group.

System object (taxonomy group)

Attribute Description Type Notes
id Unique identifier of the taxonomy group string
name Display name of the taxonomy group string
codename Codename of the taxonomy group string Generated from the taxonomy group's display name.
last_modified When was the taxonomy group last modified string ISO-8601 formatted date/time.

Every taxonomy group contains an array of term objects. Each term object contains an array of taxonomically descendant term objects.

Term object (taxonomy group)

Attribute Description Type Notes
name Display name of the taxonomy term string
codename Codename of the taxonomy term string Generated from the taxonomy term's display name.
terms Taxonomically descendant terms collection of Term objects

Example: Taxonomy group object

{
  "system": {
    "id": "f30c7f72-e9ab-8832-2a57-62944a038809",
    "name": "Personas",
    "codename": "personas",
    "last_modified": "2017-08-31T09:41:06.520241Z"
  },
  "terms": {
    # collection of Term objects
  }
}

Example: Taxonomy term object

{
  "name":"Coffee expert",
  "codename":"coffee_expert",
  "terms":[
    {
      "name":"Barista",
      "codename":"barista",
      "terms":[
        
      ]
    },
    {
      "name":"Cafe owner",
      "codename":"cafe_owner",
      "terms":[
        
      ]
    }
  ]
}
Suggest Edits

View a taxonomy group

Retrieve a specific taxonomy group from your project by specifying its codename.

 
gethttps://deliver.kenticocloud.com/project_id/taxonomies/taxonomy_group_codename
curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/taxonomies/personas' \
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

TaxonomyGroup taxonomyGroup = await client.GetTaxonomyGroupAsync("personas");
import { DeliveryClient } from 'kentico-cloud-delivery';

const deliveryClient = new DeliveryClient({
  projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.taxonomy('personas')
    .getObservable()
    .subscribe(response => console.log(response.taxonomy));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

TaxonomyGroup taxonomyGroup = client.getTaxonomyGroup("personas");
const KenticoCloud = require('kentico-cloud-delivery');

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.taxonomy('personas')
    .getObservable()
    .subscribe(response => console.log(response.taxonomy));
import KenticoCloud

let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")

client.getTaxonomyGroup(taxonomyGroupName: "personas", completionHandler: { (isSuccess, deliveryItem, error) in
   if isSuccess {
       if let taxonomyGroup = deliveryItems.item {
        // use your taxonomy group here
       }
    } else {
         if let error = error {
             print(error)
         }
    }
})
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 the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets a taxonomy group using a simple request
Taxonomy taxonomy = deliveryService.taxonomy("personas")
    .get()
    .getTaxonomy();

// Gets a taxonomy group using RxJava2
deliveryService.taxonomy("personas")
    .getObservable()
    .subscribe(new Observer<DeliveryTaxonomyResponse>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryTaxonomyResponse response) {
            // Gets the taxonomy group
            Taxonomy taxonomy = response.getTaxonomy();
        }

        @Override
        public void onError(Throwable e) {
            System.out.println(e.getMessage());
        }

        @Override
        public void onComplete() {
        }
    });
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$taxonomyGroup = $client->getTaxonomy('personas');
A binary file was returned

You couldn't be authenticated

{
  "system": {
    "id": "f30c7f72-e9ab-8832-2a57-62944a038809",
    "name": "Personas",
    "codename": "personas",
    "last_modified": "2016-10-20T13:24:00.3200182Z"
  },
  "terms": [
    {
      "name": "Coffee expert",
      "codename": "coffee_expert",
      "terms": [
        {
          "name": "Barista",
          "codename": "barista",
          "terms": []
        },
        {
          "name": "Cafe owner",
          "codename": "cafe_owner",
          "terms": []
        }
      ]
    },
    {
      "name": "Coffee enthusiast",
      "codename": "coffee_enthusiast",
      "terms": [
        {
          "name": "Coffee lover",
          "codename": "coffee_lover",
          "terms": []
        },
        {
          "name": "Coffee blogger",
          "codename": "coffee_blogger",
          "terms": []
        }
      ]
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

taxonomy_group_codename
string
required

The codename of a specific taxonomy group. Example: personas.

Headers

X-KC-Wait-For-Loading-New-Content
string

If the requested content has changed since the last request, the header determines whether to wait while fetching content. This can be useful when retrieving changed content in reaction to a webhook call. By default, when the header is not set, the API serves old content (if cached by the CDN) while it's fetching the new content to minimize wait time. To always fetch new content, set the header value to true.

 

Returns

A single Taxonomy group object if a valid taxonomy group codename was specified. If your query does not match any taxonomy group, the API returns an error response with a 404 HTTP status code.

Suggest Edits

Webhooks and notifications

 

Get notifications to your webhook endpoint whenever the content in your project changes.

The notifications are sent only when a change affects published content. For example, after modifying a content type or (un)publishing content items.

For the full list of actions that can cause a notification to be sent (via HTTP POST) to your webhook endpoint, see the list of Types and Operations.

Notification model

Each notification comes as JSON with the following attributes:

Attribute Description Type
message Information about the origin of the notification Message
data Information about the changed content Data

Signatures: To verify that a notification came from us and not from a third-party, each notification is sent with a hash signature in the X-KC-Signature header. See Notification signatures for more details.

Notification message object

The message object contains information about the origin of the notification. The attributes from the notification message object are also duplicated in the HTTP webhook header with the X-KC-Message prefix. For example, Project ID is represented as the X-KC-Message-Project-Id header.

Attribute Description Type Notes
id The ID of the notification string
type Type of the data that was changed string Valid types: asset, content_item, content_item_variant, content_type, project, project_settings, sitemap, taxonomy. For more information, see the list of types.
operation The action performed on the data string Valid operations: upsert, publish, restore_publish, unpublish, archive, restore. For more information, see the list of operations.
api_name Whether the notification is for the production or preview version of the Delivery API string Valid value: delivery_production.
project_id The ID of the project holding the changed content string
webhook_url A publicly available URL address of a webhook endpoint string Valid address format: http(s)://yourapp.com/webhook
created_timestamp Formatted UTC time and date string Valid format: YYYY-MM-DDTHH:MM:SSZ. ISO-8601 formatted string.

Notification data object

The data object contains information about the changes that affected published content. This information is contained in two objects, items and taxonomies.

Attribute Description Type
items A list of content item objects array of Item objects
taxonomies A list of taxonomy group objects array of Taxonomy group objects

Item object

Attribute Description Type
language Codename of the language variant the content is in string
type Codename of the content type the modified content item is based on string
codename Codename of the content item string

Taxonomy group object

Attribute Description Type
codename Codename of the modified taxonomy group string

Example webhook call on content change

{
  "message": {
    "id": "e86d52f9-2add-4642-a346-c5e420ca991e",
    "type": "sitemap",
    "operation": "upsert",
    "api_name": "delivery_production",
    "project_id": "6f632c14-8a50-4532-9b0e-2b9520b78982",
    "webhook_url": "https://yourapp.com/webhook",
    "created_timestamp": "2018-04-26T08:21:08.4456531Z"
  },
  "data": {
    "items": [
      {
        "language": "en-US",
        "codename": "paper_filters_for_chemex",
        "type": "accessory"
      },
      {
        "language": "en-US",
        "codename": "hario_buono_kettle",
        "type": "accessory"
      },
      {
        "language": "en-US",
        "codename": "aeropress_filters",
        "type": "accessory"
      }
    ],
    "taxonomies": []
  }
}
Suggest Edits

Types and operations

 

The type and operation attributes in the Message object tell you what data changed in your project and how.

Types

The type attribute in the notification message represents a data model in Kentico Cloud. Notifications are sent whenever a change in your project affects published content. The type attribute tells you where the change occurred.

Type Description Possible operations
asset An asset (including its asset descriptions) upsert
content_item A content item archive, restore, publish, unpublish, upsert
content_item_variant A content item variant archive, restore, publish, unpublish
content_type A content type upsert
project A project archive, restore
project_settings Project localization settings upsert
sitemap Project sitemap upsert
taxonomy Taxonomy group and its terms archive, restore, upsert

Operations

The operation attribute in the the notification message defines the action that was performed on the type.

Operation Description Applies to types
archive A data model was deleted content_item, content_item_variant, project, taxonomy
restore A data model was restored content_item, content_item_variant, project, taxonomy
restore_publish A previously published content item was restored content_item, content_item_variant
publish A content item was published content_item, content_item_variant
unpublish A content item was unpublished content_item, content_item_variant
upsert A data model was modified asset, content_item, content_type, sitemap, taxonomy

Note: The upsert operation for the content_item type occurs only when a change of content item's name (which triggers regeneration of its codename) or sitemap location affects other published content items.

Suggest Edits

Notification signatures

 

The notifications sent to a webhook come with the X-KC-Signature header. This header contains a checksum of the JSON payload that you can use to verify the authenticity of the notification. The signature is a base64 encoded hash that is generated using a HMAC SHA-256 with a secret key.

X-KC-Signature: fRbrQ1lpBSRB9T3MckJ51HDdjQ8UuV3WnjqKqirSpW8=

Verifying webhook notifications

To verify a notification, use the JSON payload (i.e., the body of the notification) and the generated webhook Secret as the secret for the HMAC function. The secret is unique for each configured webhook in your project. Once you generate a hash, compare it with the value of the X-KC-Signature header.

For example, here are a few code samples on generating the hash:

using System;
using System.Security.Cryptography;
using System.Text;

private static string GenerateHash(string message, string secret)
{
    secret = secret ?? "";
    UTF8Encoding SafeUTF8 = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false, throwOnInvalidBytes: true);
    byte[] keyBytes = SafeUTF8.GetBytes(secret);
    byte[] messageBytes = SafeUTF8.GetBytes(message);
    using (HMACSHA256 hmacsha256 = new HMACSHA256(keyBytes))
    {
        byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
        return Convert.ToBase64String(hashmessage);
    }
}
<?php

$givenSignature = $_SERVER['HTTP_X_KC_SIGNATURE'];
$computedSignature = base64_encode(hash_hmac('sha256', $json_message, $secret, true));

$result = hash_equals($givenSignature, $computedSignature);

?>
const crypto = require('crypto');

const isValidSignature = (req, secret) => {
  const givenSignature = req.headers['X-KC-Signature'];
  const computedSignature = crypto.createHmac('sha256', secret)
    .update(req.body)
    .digest();
  return crypto.timingSafeEqual(Buffer.from(givenSignature, 'base64'), computedSignature);
}
import javax.crypto;
import javax.crypto.spec;
import javax.xml.bind;

public static String generateHash(String message, String secret) throws Exception {
    Mac sha256Hmac = Mac.getInstance("HmacSHA256");
    SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
    sha256Hmac.init(secretKeySpec);

    return Base64.getEncoder().encodeToString(sha256Hmac.doFinal(message.getBytes(StandardCharsets.UTF_8)));
}
Suggest Edits

Content Management API

Manage content in Kentico Cloud projects or import your content from a different system.

 

Premium feature

The Content Management API requires a Professional plan or higher. See Pricing for more details.

The Content Management API (CM API) is a secure REST API that provides read/write access to your Kentico Cloud projects.

Use the API to migrate your existing content into your Kentico Cloud project, or update content in unpublished content items. Note that the API cannot be used on published content items unless you create new versions of the items first.

In the future, we plan to support working with workflows, publishing and unpublishing content using the Content Management API. See our Roadmap to find more details or to give us feedback on planned features.

When retrieving and updating content via the CM API, you always work with the latest versions of content – the same as you would see in the Kentico Cloud user interface.

Learn how to import content via the API by taking the tutorial on Importing to Kentico Cloud.

API requests limits

The requests made to the Content Management API count towards the overall API calls limit set in our Fair Use Policy. For more information, see Pricing FAQ on our Kentico Cloud website.

The base URL for all requests is https://manage.kenticocloud.com/v1/projects/<YOUR_PROJECT_ID>.

All requests to the API must be made securely with HTTPS with TLS 1.2 and authenticated with a valid API key. Requests to the API are rate limited and uncached.

Note: The CM API does not provide any content filtering options and is not optimized for content delivery. If you need to deliver larger amounts of content, filter it, and leverage content caching, we recommend using the Delivery API instead.

curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
Suggest Edits

API key scope and validity

The API key for the Content Management API is valid only for a certain amount of time after being generated.

 

By default, the API keys for the Content Management API are valid for 90 days. The reason for the expiration is that the Content Management API is not designed for continuous content migration or modification, but rather a one-time processing of data into the system.

The scope of the API keys is per project per user. This means you need a separate API key for each of your projects.

The API Key inherits the identity and permissions of the user who generated it:

  • Operations performed with the key will show up in Revision history as changes made by that user.
  • The key can only authorize operations that the user had permission to perform at the time when the key was generated.

If you regenerate an API key before its expiration date, the system will revoke the previous API key. Requests made with a revoked API Key will receive a 403 Forbidden HTTP status code in the response.

Note: 5 days before the API key expires, we will send a notification email to users with the Manage APIs capability.

Example: API key revocation

{
    "request_id": "800000c0-0001-fc00-b63f-84710c7967bb",
    "error_code": 7,
    "message": "The provided API key was revoked. You can find a valid API key for this project in the Kentico Cloud app."
}
Suggest Edits

Rate limiting

 

Rate limits specify the number of requests you or your application can make to the Content Management API within a specific time window. There are three separate time windows (second, minute, hour) allowing a different number of requests each.

By default, the API enforces rate limits of 10 requests per second, 400 requests per minute, and 15000 requests per hour. These limits apply for each user token, i.e., the API key for the Content Management API.

When you reach the limit of a specific time window, the API will reject the request and respond with the 429 HTTP error. The response will include the Retry-After header that tells you how many seconds you need to wait before attempting further requests. Each failed request is perfectly safe to retry.

If you begin to receive 429 HTTP errors, reduce the frequency of your requests.

Note: We recommend taking the serial approach when importing content via the Content Management API. It is strongly advised not to make several API requests in parallel as this may cause unpredictable behavior and possibly lead to race conditions.

Example: Reaching the rate limit

{
    "request_id": "80000004-0002-fd00-b63f-84710c7967bb",
    "error_code": 10000,
    "message": "API rate limit exceeded. Please retry your request later."
}
Suggest Edits

Listing response

Object model descriptions of the listing responses returned by the Content management API.

 

When you request a list of content items or assets, the Content management API returns a dynamically paginated listing response limited to up to 100 objects, i.e., content items or assets, per one page.

Content items listing response

Attribute Description Type
items A list of content items array of Content item objects
pagination Information about the next page of results Pagination

Assets listing response

Attribute Description Type
assets A list of assets array of Asset objects
pagination Information about the next page of results Pagination

Pagination object

Attribute Description Type Notes
continuation_token Identifier of the next page of results string Is null when on the last page of results.
next_page URL to the next page of results string Is null when on the last page of results.

Example: Content items listing

{
  "items": [
    # array of up to 100 Content item objects
  ],
  "pagination": {
    "continuation_token": "MTAw",
    "next_page": "https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items?continuationToken=MTAw"
  }
}

Example: Assets listing

{
  "assets": [
    # array of up to 100 Asset objects
  ],
  "pagination": {
    "continuation_token": "MTAw",
    "next_page": "https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets?continuationToken=MTAw"
  }
}
Suggest Edits

Content item model

Object model description of a single content item object accessed through the Content management API.

 

The content item object contains metadata about your content, such as the name of the content item and the sitemap locations it is placed in. The content item object does not store the content itself. The content for each language variant of a content item is saved in language variants, with each content item having as many variants as there are active languages in your project.

To manage content items via the Content Management API, you need to send requests to URIs based on the following patterns:

  • Using internal IDs: <base_URL>/items/<content_item_id>
  • Using codenames: <base_URL>/items/codename/<content_item_codename>
  • Using external IDs: <base_URL>/items/external-id/<content_item_external_identifier>

To retrieve retrieve language variants of a specific content item, you can list the variants by specifying the internal ID, codename, or external ID of the content item.

Content item object

Attribute Description Type Notes
id Internal ID of the content item string
name Display name of the content item string
codename Codename of the content item string Generated from the content item's name.
type Reference to the content type the content item is based on Reference
sitemap_locations One or more references to sitemap locations array of Reference objects
external_id External ID of the content item string
last_modified When was the content item last modified string ISO-8601 formatted date/time.

Example: Content item object

{
  "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474",
  "name": "On Roasts",
  "codename": "on_roasts",
  "type": {
    "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
  },
  "sitemap_locations": [
    {
      "id": "45a123f3-1c55-c697-7dae-78369c8f1e2c"
    }
  ],
  "external_id": "59713", 
  "last_modified": "2017-04-04T13:45:30.7692802Z"
}
{
    "name": "On roasts",
    "type": {
        "codename": "article"
    },
    "sitemap_locations": [
        {
            "codename": "articles"
        }
    ],
    "external_id": "59713"
}
Suggest Edits

List content items

Retrieve a dynamically paginated list of content items.

 
gethttps://manage.kenticocloud.com/v1/projects/project_id/items
curl --request GET \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

ListingResponseModel<ContentItemModel> responseItems = await client.ListContentItemsAsync();
A binary file was returned

You couldn't be authenticated

{
  "items": [
    {
      "id": "a815faa5-009e-489b-b8bb-a7f3dda0e047",
      "name": "Office in Australia",
      "codename": "office_in_australia",
      "type": {
        "id": "e097306b-3893-4a42-9973-2525fad14d66"
      },
      "sitemap_locations": [
        {
          "id": "aac5fdf9-5179-f788-8225-3bcee3093aa4"
        },
        {
          "id": "22110d88-4b92-32a0-db61-9b8dbe401920"
        }
      ],
      "last_modified": "2016-10-20T10:50:51.0110853Z"
    },
    {
      "id": "69f5c2f3-7efd-46cb-9adc-4fd0200f81cc",
      "name": "Melbourne",
      "codename": "melbourne",
      "type": {
        "id": "fe41ae5a-5fe2-420a-8560-f7d6d3533dc2"
      },
      "sitemap_locations": [
        {
          "id": "a60fe91c-88ea-6990-fe3b-cf8f8504cd33"
        },
        {
          "id": "98c9e0f1-b6f7-510d-522a-0d39fc62aa1a"
        }
      ],
      "last_modified": "2016-09-01T08:36:30.1564913Z"
    },
    {
      "id": "e844a6aa-4dc4-464f-8ae9-f9f66cc6ab61",
      "name": "Amsterdam",
      "codename": "amsterdam",
      "type": {
        "id": "fe41ae5a-5fe2-420a-8560-f7d6d3533dc2"
      },
      "sitemap_locations": [
        {
          "id": "ef86a740-9e4c-0b33-4275-ae78558e71a7"
        },
        {
          "id": "a65962ef-fccc-2112-956b-e831bb86dec0"
        },
        {
          "id": "a60fe91c-88ea-6990-fe3b-cf8f8504cd33"
        }
      ],
      "last_modified": "2016-09-01T08:25:04.4666023Z"
    },

    # ...
    
  ],
  "pagination": {
    "continuation_token": "MTAw",
    "next_page": "https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items?continuationToken=MTAw"
  }
}
{
  "items": [],
  "pagination": {
    "continuationToken": null,
    "next_page": null
  }
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

Query Params

continuationToken
string

Determines the next page of results to retrieve. Example: MTAw.

 

Returns

A paginated listing response with an array of content item objects.

Suggest Edits

View a content item

Retrieve metadata information about a content item specified by its internal ID, codename or external ID.

If you want to retrieve content data, see how to List language variants of a content item.

 
gethttps://manage.kenticocloud.com/v1/projects/project_id/items/content_item_identifier
curl --request GET \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

ContentItemIdentifier identifier = ContentItemIdentifier.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474"));
// ContentItemIdentifier identifier = ContentItemIdentifier.ByCodename("on_roasts");
// ContentItemIdentifier identifier = ContentItemIdentifier.ByExternalId("59713");

ContentItemModel responseItems = await client.GetContentItemAsync(identifier);
A binary file was returned

You couldn't be authenticated

{
  "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474",
  "name": "On Roasts",
  "codename": "on_roasts",
  "type": {
    "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
  },
  "sitemap_locations": [
    {
      "id": "45a123f3-1c55-c697-7dae-78369c8f1e2c"
    }
  ],
  "external_id": "59713",
  "last_modified": "2017-04-04T13:45:30.7692802Z"
}
{
  "request_id": "00000000-0000-0000-8918-0080000000cd",
  "error_code": 100,
  "message": "The requested content item '59713' was not found."
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_item_identifier
string
required

An identifier of a specific content item. You can identify the item by its codename (codename/on_roasts) or its internal ID (f4b3fc05-e988-4dae-9ac1-a94aba566474) or its external ID (external-id/59713).

 

Returns

A single Content item object with metadata. To retrieve content data, see how to List language variants.

Suggest Edits

Add a content item

Create a new content item based on a specific content type. Content items do NOT contain any content themselves, but serve as wrappers for individual language variants.

To import content to a specific language variant of a content item, you can upsert a language variant.

If you are importing content from a different system and want to use the same identifiers for your content as in the previous system, use the external_id attribute to set a custom identifier for the new content item.

 
posthttps://manage.kenticocloud.com/v1/projects/project_id/items
curl --request POST \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
  "name": "On Roasts",
  "type": {
    "codename": "article"
  },
  "sitemap_locations": [
    {
      "codename": "articles"
    }
  ],
  "external_id": "59713"
}'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

ContentItemCreateModel item = new ContentItemCreateModel
{
    Name = "On Roasts",
    Type = ContentTypeIdentifier.ByCodename("article"),
    SitemapLocations = new[] { SitemapNodeIdentifier.ByCodename("articles") },
    ExternalId = "59713";
};

ContentItemModel responseItem = await client.CreateContentItemAsync(item);
A binary file was returned

You couldn't be authenticated

{
  "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474",
  "name": "On Roasts",
  "codename": "on_roasts",
  "type": {
    "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
  },
  "sitemap_locations": [
    {
      "id": "45a123f3-1c55-c697-7dae-78369c8f1e2c"
    }
  ],
  "external_id": "59713",
  "last_modified": "2017-04-04T13:45:30.7692802Z"
}
{
  "request_id": "e6368434-e500-48b4-9ffe-3cd3c0f53ac9",
  "error_code": 0,
  "message": "Provide ID of content item's content type."
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

Body Params

name
string
required

The name of the new content item. Maximum length is 50 characters. Example: Roasting coffee.

type
object
required

Reference to an existing content type. Example: {"codename": "article"} or {"id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"}.

sitemap_locations
array of objects

An array of sitemap locations in the project sitemap, defined by references to individual sitemap nodes. If you provide an empty array, the content item is removed from its position in the sitemap. Example: [{"codename": "articles"}, {"codename": "coffee"}].

external_id
string

The external ID of the new content item. Use this parameter as a unique identifier to retrieve content from a different system. Note that you cannot upsert external ID into already existing content items within the Kentico Cloud project. Example: 59713.

 

Returns

If the request was successful, the API returns a 201 Created HTTP status code along with the created Content item object.

The API returns a 400 Bad request HTTP status code when any of the following occurs:

  • The name attribute is missing, empty, or longer than 50 characters.
  • The type attribute is missing or referencing a non-existent content type.
  • The sitemap_locations attribute contains duplicate references or a reference to a non-existent sitemap location.
  • The external_id attribute contains the same value as an already existing content item within the specified project.
  • The request is malformed.
Suggest Edits

Update a content item

Update an existing content item specified by its internal ID or codename.

 
puthttps://manage.kenticocloud.com/v1/projects/project_id/items/content_item_identifier
curl --request PUT \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts  \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
  "name": "On Roasts",
  "sitemap_locations": [
    {
      "codename": "articles"
    }
  ]
}'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

ContentItemIdentifier identifier = ContentItemIdentifier.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474"));
// ContentItemIdentifier identifier = ContentItemIdentifier.ByCodename("hario_skerton_hand_grinder");

// Defines new properties of a content item
ContentItemUpdateModel item = new ContentItemUpdateModel
{
    Name = "On Roasts",
    SitemapLocations = new[] { SitemapNodeIdentifier.ByCodename("articles") }
};

ContentItemModel responseItem = await client.UpdateContentItemAsync(identifier, item);
A binary file was returned

You couldn't be authenticated

{
  "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474",
  "name": "On Roasts",
  "codename": "on_roasts",
  "type": {
    "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
  },
  "sitemap_locations": [
    {
      "id": "45a123f3-1c55-c697-7dae-78369c8f1e2c"
    }
  ],
  "external_id": "59713",
  "last_modified": "2017-04-04T13:45:30.7692802Z"
}
{
  "request_id": "00000000-0000-0000-8805-0080000000bf",
  "error_code": 5,
  "message": "The provided request body is invalid. See the 'validation_errors' attribute for more information and specify a valid JSON object.",
  "validation_errors": [
    {
      "message": "Property 'id' must be a valid Guid identifier.",
      "path": "sitemap_locations[0]",
      "line": 6,
      "position": 6
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_item_identifier
string
required

An identifier of a specific content item. You can identify the item by its codename (codename/on_roasts) or its internal ID (f4b3fc05-e988-4dae-9ac1-a94aba566474) or its external ID (external-id/59713).

Body Params

name
string
required

The name of the new content item. Maximum length is 50 characters. Example: Roasting coffee.

sitemap_locations
array of objects
required

An array of sitemap locations in the project sitemap, defined by references to individual sitemap nodes. If you provide an empty array, the content item is removed from its position in the sitemap. Example: [{"codename": "articles"}, {"codename": "coffee"}].

 

Returns

If the request was successful, the specified content item was updated and the API returns a 200 OK HTTP status code.

The API returns a 400 Bad Request HTTP status code when any of the following occurs:

  • The name attribute is missing, empty, or longer than 50 characters.
  • The sitemap_locations attribute contains duplicate references or a reference to a non-existent sitemap location.
  • The request is malformed.

The API returns a 404 Not Found HTTP status code if the content item was not found.

Suggest Edits

Upsert a content item

Add a new content item or update an existing content item specified by its external ID.

Note: If no content item with the specified external ID exists in the project, the system will try to create one. For existing content items, the API updates the content item's name and sitemap locations.

You can also specify the external ID when adding content items via the POST method.

 
puthttps://manage.kenticocloud.com/v1/projects/project_id/items/external-id/content_item_external_id
curl --request PUT \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
  "name": "On Roasts",
  "type": {
    "codename": "article"
  },
  "sitemap_locations": [
    {
      "codename": "articles"
    }
  ]
}'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

string externalId = "59713";

ContentItemUpsertModel item = new ContentItemUpsertModel()
{
    Name = "On Roasts",
    Type = ContentTypeIdentifier.ByCodename("article"),
  	SitemapLocations = new[] { SitemapNodeIdentifier.ByCodename("articles") }
};

ContentItemModel contentItemResponse = await client.UpsertContentItemByExternalIdAsync(externalId, item);
A binary file was returned

You couldn't be authenticated

{
  "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474",
  "name": "On Roasts",
  "codename": "on_roasts",
  "type": {
    "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
  },
  "sitemap_locations": [
    {
      "id": "45a123f3-1c55-c697-7dae-78369c8f1e2c"
    }
  ],
  "external_id": "59713",
  "last_modified": "2017-04-04T13:45:30.7692802Z"
}
{
  "id": "b96829e8-c00d-447f-8da8-cf4982f704fd",
  "name": "Hario Skeleton Hand Grinder",
  "codename": "hario_skeleton_hand_grinder",
  "type": {
    "id": "da4f1cb1-8a55-43e5-9fcc-67ad331c8888"
  },
  "sitemap_locations": [],
  "last_modified": "2017-09-18T06:16:15.8299043Z"
}
{
  "request_id": "00000000-0000-0000-8805-0080000000bf",
  "error_code": 5,
  "message": "The provided request body is invalid. See the 'validation_errors' attribute for more information and specify a valid JSON object.",
  "validation_errors": [
    {
      "message": "Property 'id' must be a valid Guid identifier.",
      "path": "sitemap_locations[0]",
      "line": 6,
      "position": 6
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_item_external_id
string
required

The external ID of a content item. If the specified external ID does NOT exist (i.e. there is currently no content item with the same external identifier within the current project), a new content item will be created. If a content item with the specified external ID already exists, the parameters specified in the request body will be updated. Example: 59713.

Body Params

name
string
required

The name of the new content item. Maximum length is 50 characters. Example: Roasting coffee.

type
object
required

Reference to an existing content type. Parameter is only required when creating a new content item. Example: {"codename": "article"} or {"id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"}.

sitemap_locations
array of objects
required

An array of sitemap locations in the project sitemap, defined by references to individual sitemap nodes. If you provide an empty array, the content item is removed from its position in the sitemap. Parameter is only required when updating an existing content item. Example: [{"codename": "articles"}, {"codename": "coffee"}].

 

Returns

If the request was successful, the API returns:

  • a 200 OK HTTP status code, when updating an existing content item.
  • a 201 Created HTTP status code along with a new Content item object, when creating a new content item.

The API returns a 400 Bad Request HTTP status code when any of the following occurs:

  • The name attribute is missing, empty, or longer than 50 characters.
  • The type attribute is missing or referencing a non-existent content type. Note that this attribute is only required when creating a new content item.
  • The sitemap_locations attribute contains duplicate references or a reference to a non-existent sitemap location. Note that this attribute is only required when updating an existing content item.
  • The request is malformed.
Suggest Edits

Delete a content item

Delete a content item specified by its internal ID, codename or external ID. Note that deleting a content item deletes all of its language variants as well.

If you only want to delete a specific language variant, see how to delete a language variant.

 
deletehttps://manage.kenticocloud.com/v1/projects/project_id/items/content_item_identifier
curl --request DELETE \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474 \
# --url https://manage.kenticocloud.com/v1/projects/f4b3fc05-e988-4dae-9ac1-a94aba566474/items/codename/on_roasts \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

ContentItemIdentifier identifier = ContentItemIdentifier.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474"));
// ContentItemIdentifier identifier = ContentItemIdentifier.ByCodename("on_roasts");
// ContentItemIdentifier identifier = ContentItemIdentifier.ByExternalId("59713");

await client.DeleteContentItemAsync(identifier);
A binary file was returned

You couldn't be authenticated

 
{
  "request_id": "2d2803b7-9b67-4bd8-b3d2-436aa077827f",
  "error_code": 100,
  "message": "The requested content item 'f4b3fc05-e988-4dae-9ac1-a94aba566474' was not found."
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_item_identifier
string
required

An identifier of a specific content item. You can identify the item by its codename (codename/on_roasts) or its internal ID (f4b3fc05-e988-4dae-9ac1-a94aba566474) or its external ID (external-id/59713).

 

Returns

If the request was successful, the specified content item is deleted from the project and the API responds with a 204 No Content HTTP status code. When called on a non-existent or already deleted content item, the API responds with a 404 Not Found HTTP status code.

Suggest Edits

Language variant model

Object model description of a single language variant object accessed through the Content management API.

 

The language variant object represents a localized variant of a content item. For example, when your project contains 2 active languages, each content item in that project can have 2 language variants.

Deactivated languages

If a language is deactivated in the project settings, the respective language variants cannot be retrieved via the Content Management API. In such cases, the API will return a 404 not found error.

Every language variant is always tied to a specific content item and project language. This means you need to specify identifiers for both when you request a variant, even if your project contains only a single language.

To manage language variants via the Content Management API, you need to send requests to URIs based on the following patterns:

  • Item ID + Language ID: <base_URL>/items/<content_item_id>/variants/<language_id>
  • Item ID + Language codename: <base_URL>/items/<content_item_id>/variants/codename/<language_codename>
  • Item codename + Language ID: <base_URL>/items/codename/<content_item_codename>/variants/<language_id>
  • Item codename + Language codename: <base_URL>/items/codename/<content_item_codename>/variants/codename/<language_codename>
  • Item external ID + Language ID: <base_URL>/items/external-id/<content_item_external_id>/variants/<language_id>
  • Item external ID + Language codename: <base_URL>/items/external-id/<content_item_external_id>/variants/codename/<language_codename>

These endpoints accept GET, PUT, and DELETE requests, allowing you to retrieve, upsert, and delete language variants. You can mix and match the codenames, internal IDs, and external IDs of content items, and codenames or IDs of languages when requesting language variants, depending on your preference.

Language variant object

Attribute Description Type Notes
item Reference to the content item Reference
elements List of content elements list of Content element objects
language Reference to the project language Reference Default project language will always have the ID 00000000-0000-0000-0000-000000000000.
last_modified When was the content item last modified string ISO-8601 formatted date/time.

Example: Language variant object

{
  "item": {
    "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474"
  },
  "elements": {
    "personas": [
      {
        "id": "6a372f43-ccd7-e524-6308-c2094e7b6596"
      },
      {
        "id": "4fa27320-c363-3ebe-5ab5-b531300f053f"
      }
    ],
    "title": "En Asados",
    "post_date": "2014-11-07T00:00:00Z",
    "summary": "Tostar granos de café puede tardar de 6 a 13 minutos. ...",
    "related_articles": [
      {
        "id": "b2fea94c-73fd-42ec-a22f-f409878de187"
      }
    ],
    "meta_keywords": "asados, café",
    "meta_description": "Tostar granos de café puede tardar de 6 a 13 minutos. ....",
    "url_pattern": "on-roasts"
  },
  "language": {
    "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
  },
  "last_modified": "2017-07-20T12:18:13.2848024Z"
}
{
  "elements": {
    "personas": [
      {
        "codename": "barista"
      },
      {
        "codename": "coffee_blogger"
      }
    ],
    "title": "En Asados",
    "post_date": "2014-11-07T00:00:00Z",
    "summary": "Tostar granos de café puede tardar de 6 a 13 minutos. ...",
    "related_articles": [
      {
        "codename": "coffee_processing_techniques"
      },
      {
        "codename": "origins_of_arabica_bourbon"
      }
    ],
    "meta_keywords": "asados, café",
    "meta_description": "Tostar granos de café puede tardar de 6 a 13 minutos. ...",
    "url_pattern": "on-roasts"
  }
}
Suggest Edits

Content element model

Object model descriptions of individual elements.

 

When you retrieve or update language variants, you will work with a collection of content elements. The elements collection contains the elements as defined in the content type.

Element object

The values of content elements can be strings (Text, Rich text, Date & Time, and URL slug elements), decimal numbers (Number element), and arrays of Reference objects (Multiple choice, Asset, Linked items (formerly called Modular content), and Taxonomy elements).

Note: The content elements come in the form of key-value pairs and contain only information about their values, not their type.

"elements": {
  "text": "On Roasts",
  "rich_text": "<h3>Light Roasts</h3>\n<p>Usually roasted for 6-8 minutes or simply until achieving a light brown color. This method is used for milder coffee varieties and for coffee tasting. This type of roasting allows the natural characteristics of each coffee to show.&nbsp;</p>\n<object type=\"application/kenticocloud\" data-type=\"item\" data-id=\"b96829e8-c00d-447f-8da8-cf4982f704fd\"></object>\n<p>The aroma of coffees produced from light roasts is usually more intense. The <a href=\"https://en.wikipedia.org/wiki/Cup_of_coffee\" data-new-window=\"true\">cup itself</a> is more acidic and the concentration of caffeine is higher.</p>\n<figure data-asset-id=\"3e76909f-599f-4742-b472-77fd4b510e92\"><img src=\"#\" data-asset-id=\"3e76909f-599f-4742-b472-77fd4b510e92\"></figure>\n<p>...</p>",
  "number": 11,
  "multiple_choice": [
    {
      "id": "856ae497-b967-d667-864a-2a2faa99337e"
    },
    {
      "id": "373c3948-6e0e-9b06-9807-c807982d940d"
    }
  ],
  "date___time": "2017-11-15T00:00:00Z",
  "asset": [
    {
      "id": "66d73245-10e5-4478-93e7-5609fee3cdf7"
    },
    {
      "id": "512047f1-2f7f-45fd-9e90-e71b8feae017"
    }
  ],
  "modular_content": [
    {
      "id": "33389c83-dcfe-48f9-b0ee-f94aeabd2b08"
    }
  ],
  "product_status": [
    {
      "id": "8d808da3-29de-e608-5699-8565687dd474"
    }
  ],
  "url_slug": "roasting"
}

Text element

The value of Text elements is a string with the maximum length of 100,000 characters. If empty, the value is null.

When retrieving and updating Text elements, the format of the value will be identical for both GET and PUT operations.

"product_name": "Brazil Natural Barra Grande"

Number

The value of Number elements is a decimal number. If empty, the value is null.

When retrieving and updating Number elements, the format of the value will be identical for both GET and PUT operations.

"price": 8.5

Multiple choice

The value of Multiple choice elements is an array of Reference objects. Each reference represents one of the multiple choice options, each with a unique identifier.

If the element is configured as single option (i.e., Radio buttons), it must contain a reference to exactly one option. When configured as multiple option (i.e., Checkboxes), the element can contain references to as many options as are defined in the content type. In case no option is selected, the value of the element will be an empty array.

When retrieving Multiple choice elements, the Content Management API will always reference the multiple choice options with their internal IDs. When updating Multiple choice elements via the API, you can reference an option by its internal ID or codename.

"processing": [
  {
    "id": "a831d60b-ff0e-7df1-61d2-73e851a5deab"
  }
]
"processing": [
  {
    "codename": "wet__washed_"
  }
]

Date & Time

The value of Date & time elements is an ISO-8601 formatted string. If empty, the value is null.

When retrieving and updating Date & Time elements, the format of the value will be identical for both GET and PUT operations.

"post_date": "2017-10-31T00:00:00Z"

Asset

The value of Asset elements is an array of Reference objects. Each object represents a single asset. Every asset can be referenced only once.

When retrieving Asset elements, the Content Management API will always reference assets with their internal IDs. When updating Asset elements via the API, you can reference an asset by its internal ID or external ID.

"image": [
  {
    "id": "66d73245-10e5-4478-93e7-5609fee3cdf7"
  }
]

Linked items (formerly called Modular content)

The value of Linked items elements is an array of Reference objects. Each reference represents a single content item. Every content item can be referenced only once.

When retrieving Linked items elements, the Content Management API will always reference content items with their internal IDs. When updating Linked items elements via the API, you can reference a content item by its internal ID, codename, or external ID.

"related_articles": [
  {
    "id": "117cdfae-52cf-4885-b271-66aef6825612"
  },
  {
    "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474"
  }
]
"related_articles": [
  {
    "codename": "coffee_processing_techniques"
  },
  {
    "codename": "on_roasts"
  }
]

Taxonomy

The value of Taxonomy elements is an array of Reference objects. Each reference represents a taxonomy term of a specific taxonomy group. Every taxonomy term can be referenced only once.

When retrieving Taxonomy elements, the Content Management API will always reference taxonomy terms with their internal IDs. When updating Taxonomy elements via the API, you can reference a taxonomy term by its internal ID or codename.

"personas": [
  {
    "id": "6a372f43-ccd7-e524-6308-c2094e7b6596"
  },
  {
    "id": "4fa27320-c363-3ebe-5ab5-b531300f053f"
  }
]
"personas": [
  {
    "codename": "barista"
  },
  {
    "codename": "coffee_blogger"
  }
]

URL slug

The value of URL slug elements is a string.

When retrieving and updating URL slug elements, the format of the value will be identical for both GET and PUT operations.

Automatic vs. manual mode

The URL slug element can function in two modes, automatic and manual. When creating language variants in automatic mode, the system automatically generates the element's value based on the Text element of your choice.

If you modify the element's value directly (either in UI or via API), the element switches to the manual mode. In this mode, the element does not react to changes made to the dependent Text element. Learn about using URL slugs in your projects in our Help Center.

"url_pattern": "on-roasts"
Suggest Edits

Rich text element

 

The value of Rich text elements is a string with the maximum length of 100,000 characters. By default, if there is no text, the element's value is a single empty paragraph, <p><br/><p>. The element's value can contain HTML formatted text, specific HTML elements, and must form a valid HTML fragment.

Types HTML elements Notes
Paragraphs <p>...</p>
Headings <h1>...</h1>, <h2>...</h2>, <h3>...</h3>, <h4>...</h4>
Bold text <strong>...</strong> <b> tag is not supported.
Italic text <em>...</em> <i> tag is not supported.
Lists <ol><li>...</li></ol>, <ul><li>...</li></ul>
Tables <table><tbody><tr><td>...</td></tr></tbody></table> <thead> and <tfoot> tags are not supported.
Links <a ...>...</a>
Assets <figure ...><img ...></figure>
Content items <object ...></object
Line breaks <br>

Nesting of HTML elements in Rich text

Assets, content items, headings, paragraphs and tables cannot be nested into one another and must be on the first level.

"body_copy": "... <h3>Medium roast</h3>\n<p>These exempt a <strong>stronger</strong> flavor than light <a data-item-id=\"f4b3fc05-e988-4dae-9ac1-a94aba566474\">roasts</a>. The beans are still more matte than oily.</p>\n<figure data-asset-id=\"66d73245-10e5-4478-93e7-5609fee3cdf7\"><img src=\"#\" data-asset-id=\"66d73245-10e5-4478-93e7-5609fee3cdf7\"></figure>\n<p>Caffeine contents are decreased. Medium roasts lack the grainy taste of lighter roasts. You also get a more balanced flavor, aroma and acidity.</p>\n<object type=\"application/kenticocloud\" data-type=\"item\" data-id=\"cf106f4e-30a4-42ef-b313-b8ea3fd3e5c5\"></object> ..."

Rich text – Assets

Assets in Rich text elements are defined by the block element <figure> which requires one of the following attributes: data-asset-id or data-asset-external-id. The data-asset-external-id attribute can also reference an object that was not yet imported to Kentico Cloud. For more details, see Referencing by external ID.

When inserting values in Rich text elements, the <img> element is optional. Otherwise, the <img> element requires the attributes src and data-asset-id.

<!-- Asset referenced by internal ID -->
<figure data-asset-id="512047f1-2f7f-45fd-9e90-e71b8feae017">
  <img src="#" data-asset-id="512047f1-2f7f-45fd-9e90-e71b8feae017">
</figure>

<!-- Asset referenced by external ID -->
<figure data-asset-external-id="coffee_beans"></figure>

Rich text – Content items

Content items in Rich text elements are defined by the block element <object>. The element requires the attributes type, data-type, and one of the following: data-id or data-external-id. The data-external-id attribute can also reference an object that was not yet imported to Kentico Cloud. For more details, see Referencing by external ID.

<!-- Content item referenced by internal ID -->
<object type="application/kenticocloud" data-type="item" data-id="f4b3fc05-e988-4dae-9ac1-a94aba566474"></object>

<!-- Content item referenced by external ID -->
<object type="application/kenticocloud" data-type="item" data-external-id="59713"></object>

Rich text – Links

Links in Rich text elements are defined as the HTML a element, for example, <a href="#">Link</a>. These links can be used for URL addresses, email addresses, assets, and content items. For each of the link types, the <a> element has a different set of required attributes.

Links to a URL address

Requires the attribute href.

Inserting URL values

When inserting URL values, the system might add the http:// prefix in case the provided URL is invalid or not safe. For example, URLs using the javascript protocol will be prefixed. URL values starting with /, ?, or # are allowed.

Examples of how inserted URLs are stored:

  • http://example.comhttp://example.com
  • https://example.comhttps://example.com
  • ftp://example.comftp://example.com
  • example.comhttp://example.com
  • about-us.htmlhttp://about-us.html
  • /about-us.html/about-us.html
  • ?query?query
  • #anchor#anchor
  • javascript:alert()http://javascript:alert()
  • javascript://%0aalert()http://javascript://%0aalert()
  • data:text/html,<script>alert()</script>http://data:text/html,<script>alert()</script>

Optionally, if the link should open in a new window, the <a> element can specify the attribute data-new-window set to true.

<!-- Link to URL address -->
<a href="https://example.com">example link</a>

<!-- Link to URL address that opens in a new window -->
<a href="https://example.com" data-new-window="true">example link</a>

Link with an email address

Requires the attribute data-email-address. Optionally, the link can contain the attribute data-email-subject.

<a data-email-address="cloud@kentico.com" data-email-subject="An inquisitive question">reach out</a>

Link to an asset

Requires one of the following attributes: data-asset-id or data-asset-external-id. The data-asset-external-id attribute can also reference an object that was not yet imported to Kentico Cloud. For more details, see Referencing by external ID.

<!-- Link to an asset referenced by internal ID -->
<a data-asset-id="0b590263-3fe5-4773-afae-5a3f6e511e66">Hario Mini Mill</a>

<!-- Link to an asset referenced by external ID -->
<a data-asset-external-id="hario_mini">Hario Mini Mill</a>

Link to a content item

Requires one of the following attributes: data-item-id or data-item-external-id. The data-item-external-id attribute can also reference an object that was not yet imported to Kentico Cloud. For more details, see Referencing by external ID.

<!-- Link to a content item referenced by internal ID -->
<a data-item-id="f4b3fc05-e988-4dae-9ac1-a94aba566474">On Roasts</a>

<!-- Link to a content item referenced by external ID -->
<a data-item-external-id="on_roasts">On Roasts</a>

Rich text – Lists

Lists in Rich text elements are defined as standard HTML lists, either ordered (<ol>) or unordered (<ul>). Each list item can contain another nested list, a piece of text, or be empty.

<ol>
  <li>A list item</li>
  <li></li>
  <li>Another list item
    <ul>
      <li>Nested list item</li>
    </ul>
  </li>
</ol>

Rich text – Tables

Tables in Rich text elements are defined as standard HTML tables with the table cells and rows contained within the <tbody> element. Note that the tables cells and rows cannot be merged.

<table><tbody>
  <tr>
    <td>Type A</td><td>Type B</td><td>Type C</td>
  </tr>
  <tr>
    <td>12.4</td><td>3.14</td><td>34.1</td>
  </tr>
</tbody></table>
Suggest Edits

Reference object

Reference other objects either by their internal IDs, codenames or external IDs.

 

References provide a way of specifying links to other objects in the system. For example, to specify a content type when creating content items, you need to refer to the content type object using either the object's internal ID or codename. Certain objects, such as content items and assets, allow referencing by external ID. You can always reference other objects only by a single property – internal ID, codename, or external ID.

Referencing with external IDs

External ID is a custom identifier of an object. You can use external IDs to reference the following objects in content elements:

See Referencing by external ID for more details.

Reference object

Attribute Description Type
id The internal ID of the referenced object string
codename The codename of the referenced object string
external_id The external ID of the referenced object string

Example: Referencing content items

"related_articles": [
  {
    "id": "117cdfae-52cf-4885-b271-66aef6825612"
  },
  {
    "id": "b2fea94c-73fd-42ec-a22f-f409878de187"
  }
]
"related_articles": [
  {
    "codename": "coffee_processing_techniques"
  },
  {
    "codename": "origins_of_arabica_bourbon"
  }
]
"related_articles": [
  {
    "external_id": "59713"
  },
  {
    "external_id": "59831"
  }
]
Suggest Edits

Referencing by external ID

Reference other objects by their external IDs.

 

External ID is a custom identifier of an object. Similarly to the internal ID of an object, external ID is set once when the object is created and cannot be changed later.

You can use external IDs to reference the following objects in content elements:

By using external IDs to reference other objects in your project, you can import your content in the order you prefer. For example, when importing multiple articles that contain images, you can reference these images with external IDs, such as roaster or coffee-cup, before uploading them. The referenced images will be visible in the Kentico Cloud UI only after you add them as assets via the API. With this approach, you can choose whether you want to create content items first and then upload binary files for assets, or vice versa.
This means you can use external IDs to create references to non-existing objects and only add the objects via the Content Management API afterwards.

Note: References to non-existent objects will be stored and retrieved via the API as internal IDs. See the example of the API endpoints on the right.

Referencing non-existing objects

The Content Management API supports referencing non-existing objects in the following content elements:

  • Linked items element (formerly called Modular content element)
  • Asset element
  • Rich Text element (as assets, content items, and links)

To learn more, see the tutorial on Importing linked content.

If you want to check whether any content elements are referencing non-existing objects in your project, see Validate project content.

Restricted View

There is a restricted view of the not yet imported objects referenced by external IDs in Kentico Cloud. Non-existing content items and Assets referenced in content elements cannot be displayed in Kentico Cloud project unless you create the referenced objects via the API.

To add the the missing objects, see:

Example: Referencing non-existing content items

"related_articles": [
  {
    "external_id": "59713"
  },
  {
    "external_id": "59831"
  }
]
"related_articles": [
  {
    "id": "dec11987-5df6-5ec1-9c78-b51c28d7645a"
  },
  {
    "id": "c7a9b591-7d3a-50a9-90e5-9d484d0e3b8c"
  }
]
Suggest Edits

List language variants of an item

Retrieve a list of language variants of a content item specified by its internal ID, codename or external ID.

If you want to retrieve metadata information about the parent content item, see how to View a content item.

 
gethttps://manage.kenticocloud.com/v1/projects/project_id/items/content_item_identifier/variants
curl --request GET \
  --url https://manage.kenticocloud.com/projects/v1/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants \
# --url https://manage.kenticocloud.com/projects/v1/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants \
# --url https://manage.kenticocloud.com/projects/v1/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants \ 
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

ContentItemIdentifier identifier = ContentItemIdentifier.ById((Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474")));
// ContentItemIdentifier identifier = ContentItemIdentifier.ByCodename("on_roasts");
// ContentItemIdentifier identifier = ContentItemIdentifier.ByExternalId("59713");

IEnumerable<ContentItemVariantModel<MyContentTypeModel>> responseVariants = await client.ListContentItemVariantsAsync<MyContentTypeModel>(identifier);
A binary file was returned

You couldn't be authenticated

[
  {
    "item": {
      "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474"
    },
    "elements": {
      "personas": [
        {
          "id": "6a372f43-ccd7-e524-6308-c2094e7b6596"
        },
        {
          "id": "4fa27320-c363-3ebe-5ab5-b531300f053f"
        }
      ],
      "title": "On Roasts",
      "post_date": "2014-11-07T00:00:00Z",
      "summary": "Roasting coffee beans can take from 6 to 13 minutes. Different roasting times produce different types of coffee, with varying concentration of caffeine and intensity of the original flavor.",
      "related_articles": [
        {
          "id": "117cdfae-52cf-4885-b271-66aef6825612"
        },
        {
          "id": "b2fea94c-73fd-42ec-a22f-f409878de187"
        }
      ],
      "meta_keywords": "roasts, coffee",
      "meta_description": "Roasting coffee beans can take from 6 to 13 minutes. Different roasting times produce different types of coffee.",
      "url_pattern": "on-roasts"
    },
    "language": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "last_modified": "2017-04-04T13:45:30.7692802Z"
  },
  {
    "item": {
      "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474"
    },
    "elements": {
      "personas": [
        {
          "id": "6a372f43-ccd7-e524-6308-c2094e7b6596"
        },
        {
          "id": "4fa27320-c363-3ebe-5ab5-b531300f053f"
        }
      ],
      "title": "En Asados",
      "post_date": "2014-11-07T00:00:00Z",
      "summary": "Tostar granos de café puede tardar de 6 a 13 minutos. Diferentes tiempos de asado producen diferentes tipos de café, con diferentes concentraciones de cafeína y intensidad de sabor.",
      "related_articles": [
        {
          "id": "b2fea94c-73fd-42ec-a22f-f409878de187"
        }
      ],
      "meta_keywords": "asados, café",
      "meta_description": "Tostar granos de café puede tardar de 6 a 13 minutos. Diferentes tiempos de asado producen diferentes tipos de café, con diferentes concentraciones de cafeína y intensidad de sabor.",
      "url_pattern": "on-roasts"
    },
    "language": {
      "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
    },
    "last_modified": "2017-07-20T12:18:13.2848024Z"
  }
]
{
  "request_id": "00000000-0000-0000-9105-0080000000bf",
  "error_code": 100,
  "message": "The requested content item '4db9f4da-827b-4400-87c9-c47d44fba65d' was not found."
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_item_identifier
string
required

An identifier of a specific content item. You can identify the item by its codename (codename/on_roasts) or its internal ID (f4b3fc05-e988-4dae-9ac1-a94aba566474) or its external ID (external-id/59713).

 

Returns

An array of Language variant objects for the specified content item.

Suggest Edits

View a language variant

Retrieve content of a language variant of a content item.

The content item can be specified by its internal ID, codename or external ID. Language can be specified by its internal ID or codename.

If you want to retrieve metadata information about the parent content item, see how to View a content item.

 
gethttps://manage.kenticocloud.com/v1/projects/project_id/items/content_item_identifier/variants/language_identifier
curl --request GET \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/codename/es-ES \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/codename/es-ES \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/codename/es-ES \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474"));
// ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByCodename("on_roasts");
// ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByExternalId("59713");

LanguageIdentifier languageIdentifier = LanguageIdentifier.ById(Guid.Parse("d1f95fde-af02-b3b5-bd9e-f232311ccab8"));
// LanguageIdentifier languageIdentifier = LanguageIdentifier.ByCodename("es-ES");

ContentItemVariantIdentifier variantIdentifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier);

ContentItemVariantModel<MyContentTypeModel> responseVariant = await client.GetContentItemVariantAsync<MyContentTypeModel>(variantIdentifier);

A binary file was returned

You couldn't be authenticated

{
  "item": {
    "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474"
  },
  "elements": {
    "personas": [
      {
        "id": "6a372f43-ccd7-e524-6308-c2094e7b6596"
      },
      {
        "id": "4fa27320-c363-3ebe-5ab5-b531300f053f"
      }
    ],
    "title": "En Asados",
    "post_date": "2014-11-07T00:00:00Z",
    "summary": "Tostar granos de café puede tardar de 6 a 13 minutos. Diferentes tiempos de asado producen diferentes tipos de café, con diferentes concentraciones de cafeína y intensidad de sabor.",
    "related_articles": [
      {
        "id": "b2fea94c-73fd-42ec-a22f-f409878de187"
      }
    ],
    "meta_keywords": "asados, café",
    "meta_description": "Tostar granos de café puede tardar de 6 a 13 minutos. Diferentes tiempos de asado producen diferentes tipos de café, con diferentes concentraciones de cafeína y intensidad de sabor.",
    "url_pattern": "on-roasts"
  },
  "language": {
    "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
  },
  "last_modified": "2017-11-02T09:01:05.0552136Z"
}
{
  "request_id": "00000000-0000-0000-c813-0080000000c3",
  "error_code": 103,
  "message": "The requested content item variant was not found."
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_item_identifier
string
required

An identifier of a specific content item. You can identify the item by its codename (codename/on_roasts) or its internal ID (f4b3fc05-e988-4dae-9ac1-a94aba566474) or its external ID (external-id/59713).

language_identifier
string
required

An identifier of a project lanuguage. You can identify the language by its codename (codename/es-ES) or its ID (d1f95fde-af02-b3b5-bd9e-f232311ccab8).

 

Returns

A single Language variant object for the specified content item in the specified project language.

The API returns a 404 HTTP error in the following cases:

  • The specified content item was not found.
  • The specified project language is deactivated or does not exist.
  • The language variant does not exist in the specified language.
Suggest Edits

Upsert a language variant

Add content to a variant in an active project language, or update an existing language variant.

The content item can be specified by its internal ID, codename or external ID. Language can be specified by its internal ID or codename.

Note: Only the elements specified in the request body will be modified. Any existing comments attached to these elements will be lost on update.

 
puthttps://manage.kenticocloud.com/v1/projects/project_id/items/content_item_identifier/variants/language_identifier
curl --request PUT \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/codename/es-ES \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/codename/es-ES \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/codename/es-ES \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
  "elements": {
    "personas": [
      {
        "codename": "barista"
      },
      {
        "codename": "coffee_blogger"
      }
    ],
    "title": "En Asados",
    "post_date": "2014-11-07T00:00:00Z",
    "summary": "Tostar granos de café puede tardar de 6 a 13 minutos. ...",
    "related_articles": [
      {
        "codename": "coffee_processing_techniques"
      },
      {
        "codename": "origins_of_arabica_bourbon"
      }
    ],
    "meta_keywords": "asados, café",
    "meta_description": "Tostar granos de café puede tardar de 6 a 13 minutos. ...",
    "url_pattern": "on-roasts"
  }
}'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

// Elements to update
MyContentTypeModel stronglyTypedElements = new MyContentTypeModel
{
    Title = "En Asados",
    PostDate = new DateTime(2014, 11, 7),
    Summary = "Tostar granos de café puede tardar de 6 a 13 minutos. ...",
    RelatedArticles = new [] { ContentItemIdentifier.ByCodename("coffee_processing_techniques"), ContentItemIdentifier.ByCodename("origins_of_arabica_bourbon") },
    UrlPattern = "on-roasts",
    MetaKeywords = "asados, café",
    MetaDescription = "Tostar granos de café puede tardar de 6 a 13 minutos. ...",
    Personas = new [] { TaxonomyTermIdentifier.ByCodename("barista"), TaxonomyTermIdentifier.ByCodename("coffee_blogger") }
};

ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474"));
// ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByCodename("on_roasts");
// ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByExternalId("59713");

LanguageIdentifier languageIdentifier = LanguageIdentifier.ById(Guid.Parse("d1f95fde-af02-b3b5-bd9e-f232311ccab8"));
// LanguageIdentifier languageIdentifier = LanguageIdentifier.ByCodename("es-ES");


ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier);

ContentItemVariantModel<MyContentTypeModel> responseVariant = await client.UpsertContentItemVariantAsync<MyContentTypeModel>(identifier, stronglyTypedElements);
A binary file was returned

You couldn't be authenticated

{
  "item": {
    "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474"
  },
  "elements": {
    "personas": [
      {
        "id": "6a372f43-ccd7-e524-6308-c2094e7b6596"
      },
      {
        "id": "4fa27320-c363-3ebe-5ab5-b531300f053f"
      }
    ],
    "title": "En Asados",
    "post_date": "2014-11-07T00:00:00Z",
    "summary": "Tostar granos de café puede tardar de 6 a 13 minutos. Diferentes tiempos de asado producen diferentes tipos de café, con diferentes concentraciones de cafeína y intensidad de sabor.",
    "related_articles": [
      {
        "id": "b2fea94c-73fd-42ec-a22f-f409878de187"
      }
    ],
    "meta_keywords": "asados, café",
    "meta_description": "Tostar granos de café puede tardar de 6 a 13 minutos. Diferentes tiempos de asado producen diferentes tipos de café, con diferentes concentraciones de cafeína y intensidad de sabor.",
    "url_pattern": "on-roasts"
  },
  "language": {
    "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
  },
  "last_modified": "2017-11-02T09:01:05.0552136Z"
}
{
  "item": {
    "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474"
  },
  "elements": {
    "personas": [
      {
        "id": "6a372f43-ccd7-e524-6308-c2094e7b6596"
      },
      {
        "id": "4fa27320-c363-3ebe-5ab5-b531300f053f"
      }
    ],
    "title": "En Asados",
    "post_date": "2014-11-07T00:00:00Z",
    "summary": "Tostar granos de café puede tardar de 6 a 13 minutos. Diferentes tiempos de asado producen diferentes tipos de café, con diferentes concentraciones de cafeína y intensidad de sabor.",
    "related_articles": [
      {
        "id": "b2fea94c-73fd-42ec-a22f-f409878de187"
      }
    ],
    "meta_keywords": "asados, café",
    "meta_description": "Tostar granos de café puede tardar de 6 a 13 minutos. Diferentes tiempos de asado producen diferentes tipos de café, con diferentes concentraciones de cafeína y intensidad de sabor.",
    "url_pattern": "on-roasts"
  },
  "language": {
    "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
  },
  "last_modified": "2017-11-02T09:01:05.0552136Z"
}
{
  "request_id": "00000000-0000-0000-b919-0080000000d1",
  "error_code": 5,
  "message": "The provided request body is invalid. See the 'validation_errors' attribute for more information and specify a valid JSON object.",
  "validation_errors": [
    {
      "message": "Value '2014-13-07T00:00:00Z' cannot be assigned to an element of 'DateTime' type.",
      "path": "elements.post_date"
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_item_identifier
string
required

An identifier of a specific content item. You can identify the item by its codename (codename/on_roasts) or its internal ID (f4b3fc05-e988-4dae-9ac1-a94aba566474) or its external ID (external-id/59713).

language_identifier
string
required

An identifier of a project lanuguage. You can identify the language by its codename (codename/es-ES) or its ID (d1f95fde-af02-b3b5-bd9e-f232311ccab8).

Body Params

elements
object
required

Specifies which content elements to update. Each content element is represented as a key-value pair. The element values can be strings, numbers, or Reference objects, depending on the element type. If you don't provide any value for the elements attribute, the language variant will not be modified. Example: {"title": "En Asados", "post_date": "2014-11-07T00:00:00Z"}.

 

Returns

If the request was successful, the API returns:

  • a 200 OK HTTP status code, when updating content in an existing language variant.
  • a 201 Created HTTP status code along with a new Language variant object, when creating a new language variant.

The API returns a 404 HTTP error in the following cases:

  • The specified content item does not exist.
  • The specified project language is deactivated or does not exist.
  • The language variant was previously deleted.

The API returns a 400 HTTP error in the following cases:

  • The request is malformed.
  • The provided request body does not match the content type. For example, when the body contains excessive elements or type mismatch.
Suggest Edits

Delete a language variant

Delete a specific language variant.

The content item can be specified by its internal ID, codename or external ID. Language can be specified by its internal ID or codename.
Note that when you delete the last variant of a content item, the whole content item is deleted.

If you want to delete all language variants of a content item, see how to Delete a content item.

 
deletehttps://manage.kenticocloud.com/v1/projects/project_id/items/content_item_identifier/variants/language_identifier
curl --request DELETE \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/codename/es-ES \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/codename/es-ES \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/codename/es-ES \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474"));
// ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByCodename("on_roasts");
// ContentItemIdentifier itemIdentifier = ContentItemIdentifier.ByExternalId("59713");

LanguageIdentifier languageIdentifier = LanguageIdentifier.ById(Guid.Parse("d1f95fde-af02-b3b5-bd9e-f232311ccab8"));
// LanguageIdentifier languageIdentifier = LanguageIdentifier.ByCodename("es-ES");

ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier);

await client.DeleteContentItemVariantAsync(identifier);

A binary file was returned

You couldn't be authenticated

 
{
  "request_id": "00000000-0000-0000-c813-0080000000c3",
  "error_code": 103,
  "message": "The requested content item variant was not found."
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

content_item_identifier
string
required

An identifier of a specific content item. You can identify the item by its codename (codename/on_roasts) or its internal ID (f4b3fc05-e988-4dae-9ac1-a94aba566474) or its external ID (external-id/59713).

language_identifier
string
required

An identifier of a project lanuguage. You can identify the language by its codename (codename/es-ES) or its ID (d1f95fde-af02-b3b5-bd9e-f232311ccab8).

 

Returns

If the request was successful, the specified language variant is deleted from the project and the API responds with a 204 HTTP status code.

The API returns a 404 HTTP error in the following cases:

  • The specified content item was not found.
  • The specified project language is deactivated or does not exist.
  • The language variant does not exist in the specified language.
Suggest Edits

Asset model

Object model description of a single asset object accessed via the Content management API.

 

Assets in Kentico Cloud consist of a reference to a binary file and metadata describing the file. Each binary file can be referenced only by a single asset. Once an asset is created, the file it references cannot be changed, you can only modify the asset's descriptions and title. Note that binary files that are not used by any assets will not be visible in the Kentico Cloud UI.

Creating new assets

Adding an asset is a 2-step process:

  1. Upload a binary file – after uploading, you get a file reference to your file.
  2. Create a new asset – use the file reference to link the asset with your file.

Asset object

Attribute Description Type Notes
id Internal identifier of the asset string
file_name Name of the binary file associated with the asset string Determined by the file referenced in the file_reference attribute.
title Display name of the asset string The title can be specified when adding assets, updating assets or upserting assets. If not specified, the title attribute is null.
image_width Width of the image in pixels number Determined by the file referenced in the file_reference attribute. Is null if the file is not an image.
image_height Height of the image in pixels number Determined by the file referenced in the file_reference attribute. Is null if the file is not an image.
size Size of the binary file in bytes number Determined by the file referenced in the file_reference attribute.
type MIME type of the file string Determined by the file referenced in the file_reference attribute.
file_reference Reference to the binary file associated with the asset Asset file reference object The value of the attribute cannot be changed.
descriptions Asset descriptions for each active language array of Asset description objects
external_id External identifier of the asset string The external ID can be specified when adding assets (POST /assets) or upserting assets (PUT /assets/external-id/<external_id>). If not specified, the external_id attribute is not present.
last_modified When was the asset last modified string ISO-8601 formatted date/time.

Asset file reference object

A file reference points to a specific binary file uploaded to your project.

Attribute Description Type Notes
id Internal identifier of the binary file string
type Type of the reference string The only allowed type is internal.

Asset description object

An asset description defines a description of an asset for a single language.

Attribute Description Type Notes
language Reference to the language the asset description is in Reference object
description Description of the asset string If empty, the value is null.

Example: Asset object

{
  "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  "file_name": "which-brewing-fits-you-1080px.jpg",
  "title": "Coffee Brewing Techniques",
  "size": 125770,
  "type": "image/jpeg",
  "image_width": 1000,
  "image_height": 666,
  "file_reference": {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "type": "internal"
  },
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Técnicas para hacer café"
    }
  ],
  "last_modified": "2017-09-12T08:29:36.1645977Z"
}
Suggest Edits

List assets

Retrieve a dynamically paginated list of assets.

 
gethttps://manage.kenticocloud.com/v1/projects/project_id/assets
curl --request GET \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

ListingResponseModel<AssetModel> responseAssets = await client.ListAssetsAsync();
A binary file was returned

You couldn't be authenticated

{
  "assets": [
  {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "file_name": "which-brewing-fits-you-1080px.jpg",
    "title": "Coffee Brewing Techniques",
    "size": 125770,
    "type": "image/jpeg",
    "image_width": 1000,
    "image_height": 666,
    "file_reference": {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "type": "internal"
    },
    "descriptions": [
    {
      "language": {
      "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
      "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Técnicas para hacer café"
    }
    ],
    "last_modified": "2017-09-12T08:29:36.1645977Z"
  },
  {
	"id": "8858d272-777b-43bd-93be-53a98be97569",
	"file_name": "cafe05.jpg",
	"title": "Café - Los Angeles",
	"size": 114844,
	"type": "image/jpeg",
	"image_width": 849,
	"image_height": 565,
    "file_reference": {
    "id": "8858d272-777b-43bd-93be-53a98be97569",
    "type": "internal"
    },
    "descriptions": [
    {
      "language": {
      "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Dancing Goat Café - Los Angeles"
    },
    {
      "language": {
      "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Dancing Goat Café - Los Angeles"
    }
    ],
    "last_modified": "2017-07-04T10:29:35.0964697Z"
  },
  {
	"id": "32d055c4-8b32-48f2-881d-058a1854e36e",
	"file_name": "cafe06.jpg",
	"title": "Café - New York",
	"size": 275350,
	"type": "image/jpeg",
	"image_width": 849,
	"image_height": 565,
    "file_reference": {
    "id": "32d055c4-8b32-48f2-881d-058a1854e36e",
    "type": "internal"
    },
    "descriptions": [
    {
      "language": {
      "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Dancing Goat Café - New York"
    },
    {
      "language": {
      "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Dancing Goat Café - New York"
    }
    ],
    "last_modified": "2017-07-04T10:30:24.2190457Z"
  },
  
  # ...
  
  ],
  "pagination": {
  "continuation_token": "MTAw",
  "next_page": "https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets?continuationToken=MTAw"
  }
}
{
  "assets": [],
  "pagination": {
      "continuationToken": null,
      "next_page": null
  }
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

Query Params

continuationToken
string

Determines the next page of results to retrieve. Example: MTAw.

 

Returns

A paginated listing response with an array of assets from the specified project.

Suggest Edits

View an asset

Retrieve information about a single asset specified by its internal ID or external ID.

 
gethttps://manage.kenticocloud.com/v1/projects/project_id/assets/asset_identifier
curl --request GET \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/fcbb12e6-66a3-4672-85d9-d502d16b8d9c \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/external-id/which-brewing-fits-you \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

AssetIdentifier identifier = AssetIdentifier.ById(Guid.Parse("fcbb12e6-66a3-4672-85d9-d502d16b8d9c"));
// AssetIdentifier identifier = AssetIdentifier.ByExternalId("which-brewing-fits-you");

AssetModel responseAssets = await client.GetAssetAsync(identifier);
A binary file was returned

You couldn't be authenticated

{
   "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
   "file_name": "which-brewing-fits-you-1080px.jpg",
   "title": "Coffe Brewing Techniques",
   "size": 125770,
   "type": "image/jpeg",
   "image_width": 1000,
   "image_height": 666,
   "file_reference": {
       "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
       "type": "internal"
   },
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Técnicas para hacer café"
    }
  ],
  "last_modified": "2017-09-12T08:29:36.1645977Z"
}
{
  "request_id": "00000000-0000-0000-0e3f-0080000000d9",
  "error_code": 105,
  "message": "The requested asset 'fcbb12e6-66a3-4672-85d9-d502d16b8d9d' was not found."
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

asset_identifier
string
required

An identifier of a specific asset. You can identify the asset by its internal ID (fcbb12e6-66a3-4672-85d9-d502d16b8d9c) or its external ID (external-id/which-brewing-fits-you).

 

Returns

A single Asset object with metadata about the asset and the referenced binary file.

Suggest Edits

Upload a binary file

Add a new file. The uploaded file will not be visible in the Kentico Cloud UI unless there is an asset using it, see how to Add an asset.

Note: Maximum size limit for binary files is 100 MB.

 
posthttps://manage.kenticocloud.com/v1/projects/project_id/files/file_name
curl --request POST \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/files/which-brewing-fits-you-1080px.jpg \
  --data-binary "@which-brewing-fits-you-1080px.jpg" \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: image/jpeg' \
  --header 'Content-length: 125770'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

string filePath = Path.Combine(AppContext.BaseDirectory, @"<YOUR_PATH>\which-brewing-fits-you-1080px.jpg");
string contentType = "image/jpeg";

// Binary file reference to be used when adding a new asset
FileReference fileReference = await client.UploadFileAsync(new FileContentSource(filePath, contentType));

// To create an asset, see the "Add an asset" endpoint
A binary file was returned

You couldn't be authenticated

{
  "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
  "type": "internal"
}
{
  "request_id": "00000000-0000-0000-c403-0080000000c2",
  "error_code": 205,
  "message": "The request does not contain required header Content-Type."
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

file_name
string
required

The name of the uploaded binary file. The file_name parameter specified in the URL will be used for the asset name when creating an asset. Example: which-brewing-fits-you-1080px.jpg.

Headers

Content-type
string
required

Specifies the media type of the binary data. Example: image/jpeg, application/zip.

Content-length
int32
required

Specifies the size of the binary file in bytes. Example: 125770.

 

Returns

If the request was successful, the API returns a 200 OK HTTP status code along with a file reference to the uploaded binary file.

The API returns a 400 Bad Request HTTP status code when any of the following occurs:

  • The provided binary file is too large. The maximum size limit is 100 MB.
  • The Content-type header is missing.
  • The Content-length header is missing.
  • The request is malformed.
Suggest Edits

Add an asset

Use a file reference to link an existing binary file to a new asset. You can also create assets by upserting (PUT /assets/external-id/<external_id>), see Upsert an asset.

Note: Each binary file can be referenced only by a single asset.

 
posthttps://manage.kenticocloud.com/v1/projects/project_id/assets
curl --request POST \
  --url https://manage.kenticocloud.com/projects/v1/975bf280-fd91-488c-994c-2f04416e5ee3/assets \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
  "file_reference": {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "type": "internal"
  },
  "title": "Coffee Brewing Techniques",
  "external_id": "which-brewing-fits-you",
  "descriptions": [
    {
      "language": {
        "codename": "en-US"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "codename": "es-ES"
      },
      "description": "Técnicas para hacer café"
    }
  ]
}'
using KenticoCloud.ContentManagement;
 
ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

IEnumerable<AssetDescription> descriptions = new List<AssetDescription>();

AssetUpsertModel model = new AssetUpsertModel
{
    // To create a file reference, see the "Upload a binary file" endpoint
    FileReference = fileReference,

    Title = "Coffee Brewing Techniques",
  
    Descriptions = new List<AssetDescription> 
    {
        new AssetDescription { Description = "Coffee Brewing Techniques", Language = LanguageIdentifier.ByCodename("en-US") },
        new AssetDescription { Description = "Técnicas para hacer café", Language = LanguageIdentifier.ByCodename("es-ES") }
    }
};

AssetModel assetResult = await client.CreateAssetAsync(model);
A binary file was returned

You couldn't be authenticated

{
  "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  "file_name": "which-brewing-fits-you-1080px.jpg",
  "title": "Coffee Brewing Techniques",
  "size": 125770,
  "type": "image/jpeg",
  "image_width": 1000,
  "image_height": 666,
  "file_reference": {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "type": "internal"
  },
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Técnicas para hacer café"
    }
  ],
  "external_id": "which-brewing-fits-you",
  "last_modified": "2017-09-12T08:29:36.1645977Z"
}
{
  "request_id": "00000000-0000-0000-1614-0080000000cd",
  "error_code": 5,
  "message": "The provided request body is invalid. See the 'validation_errors' attribute for more information and specify a valid JSON object.",
  "validation_errors": [
    {
      "message": "Required property 'description' not found in JSON. Path 'descriptions[0]', line 7, position 6.",
      "path": "descriptions[0]",
      "line": 7,
      "position": 6
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

Body Params

file_reference
object
required

The reference to the binary file.

file_reference.id
string
required

The ID of the referenced binary file. Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c.

file_reference.type
string
required

The type of the reference. Example: internal.

title
string

The title of the new asset. Maximum length is 50 characters. Use this parameter to better identify and filter your assets in the UI. Example: Coffee Brewing Techniques.

external_id
string

The external ID of the new asset. Use this parameter as a unique identifier for your assets. Note that you cannot upsert external ID into already existing assets within the Kentico Cloud project. Example: which-brewing-fits-you.

descriptions
array of objects
required

An array of asset descriptions.

 

Returns

If the request was successful, the API returns a 201 HTTP status code along with the created Asset object.

The API returns a 400 Bad Request HTTP status code when any of the following occurs:

  • The descriptions attribute contains invalid asset description objects.
  • The file_reference attribute is missing or references a file that is already used in an asset.
  • The title attribute is longer than 50 characters.
  • The external_id attribute contains the same value as an already existing asset within the specified project.
  • The request is malformed.
Suggest Edits

Update an asset

Modify properties of an asset specified by its internal ID.

Note: This endpoint only allows updating of asset descriptions and title.

 
puthttps://manage.kenticocloud.com/v1/projects/project_id/assets/asset_id
curl --request PUT \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/fcbb12e6-66a3-4672-85d9-d502d16b8d9c \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
  --data '
{
  "title": "Coffe Brewing Techniques",
  "descriptions": [
    {
      "language": {
        "codename": "en-US"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "codename": "es-ES"
      },
      "description": "Técnicas para hacer café"
    }
  ]
}'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

AssetIdentifier identifier = AssetIdentifier.ById(Guid.Parse("fcbb12e6-66a3-4672-85d9-d502d16b8d9c"));

string title = "Coffe Brewing Techniques";

string englishDescription = "Coffee Brewing Techniques";
string spanishDescription = "Técnicas para hacer café";

LanguageIdentifier englishLanguageIdentifier = LanguageIdentifier.ByCodename("en-US");
LanguageIdentifier spanishLanguageIdentifier = LanguageIdentifier.ByCodename("es-ES");

AssetDescription englishAssetDescription = new AssetDescription { Description = englishDescription, Language = englishLanguageIdentifier };
AssetDescription spanishAssetDescription = new AssetDescription { Description = spanishDescription, Language = spanishLanguageIdentifier };

AssetUpdateModel update = new AssetUpdateModel() { Title = title, Descriptions = new[] { spanishAssetDescription, englishAssetDescription } };

AssetModel assetResult = await client.UpdateAssetAsync(identifier, update);
A binary file was returned

You couldn't be authenticated

{
  "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  "file_name": "which-brewing-fits-you-1080px.jpg",
  "title": "Coffee Brewing Techniques",
  "size": 125770,
  "type": "image/jpeg",
  "image_width": 1000,
  "image_height": 666,
  "file_reference": {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "type": "internal"
  },
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Técnicas para hacer café"
    }
  ],
  "last_modified": "2017-09-12T08:29:36.1645977Z"
}
{
  "request_id": "00000000-0000-0000-1614-0080000000cd",
  "error_code": 5,
  "message": "The provided request body is invalid. See the 'validation_errors' attribute for more information and specify a valid JSON object.",
  "validation_errors": [
    {
      "message": "Required property 'description' not found in JSON. Path 'descriptions[0]', line 7, position 6.",
      "path": "descriptions[0]",
      "line": 7,
      "position": 6
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

asset_id
string
required

The internal ID of the asset. Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c.

Body Params

title
string

The title of the new asset. Maximum length is 50 characters. Use this parameter to better identify and filter your assets in the UI. Example: Coffee Brewing Techniques.

descriptions
array of objects
required

An array of asset descriptions.

 

Returns

If the request was successful, the API returns a 200 OK HTTP status code along with a single Asset object.

The API returns a 400 Bad Request when any of the following occurs:

  • The descriptions attribute is missing, invalid, or contains invalid asset description objects.
  • The title attribute is longer than 50 characters.
  • The request is malformed.
Suggest Edits

Upsert an asset

Add a new asset or update an existing asset specified by its external ID.

Note: If no asset with the specified external ID exists in the project, the system will try to create one. For existing assets, the API updates only the specified asset's descriptions and title.

 
puthttps://manage.kenticocloud.com/v1/projects/project_id/assets/external-id/asset_external_id
curl --request PUT \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/external-id/which-brewing-fits-you \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
  --data '
{
  "file_reference": {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "type": "internal"
  },
  "title": "Coffe Brewing Techniques",
  "descriptions": [
    {
      "language": {
        "codename": "en-US"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "codename": "es-ES"
      },
      "description": "Técnicas para hacer café"
    }
  ]
}'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

CancellationTokenSource source = new CancellationTokenSource();
byte[] content = await System.IO.File.ReadAllBytesAsync("./which-brewing-fits-you-1080px.jpg", source.Token);

string fileName = "which-brewing-fits-you-1080px.jpg";
string contentType = "image/jpeg";

string externalId = "which-brewing-fits-you";

string title = "Coffe Brewing Techniques";

string englishDescription = "Coffee Brewing Techniques";
string spanishDescription = "Técnicas para hacer café";

LanguageIdentifier englishLanguageIdentifier = LanguageIdentifier.ByCodename("en-US");
LanguageIdentifier spanishLanguageIdentifier = LanguageIdentifier.ByCodename("es-ES");

AssetDescription englishAssetDescription = new AssetDescription { Description = englishDescription, Language = englishLanguageIdentifier };
AssetDescription spanishAssetDescription = new AssetDescription { Description = spanishDescription, Language = spanishLanguageIdentifier };

IEnumerable<AssetDescription> descriptions = new[] { englishAssetDescription, spanishAssetDescription };

AssetModel assetResult = await client.UpsertAssetByExternalIdAsync(externalId, new FileContentSource(content, fileName, contentType), new AssetUpdateModel { Descriptions = descriptions, Title = title });
A binary file was returned

You couldn't be authenticated

{
  "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  "file_name": "which-brewing-fits-you-1080px.jpg",
  "title": "Coffee Brewing Techniques",
  "size": 125770,
  "type": "image/jpeg",
  "image_width": 1000,
  "image_height": 666,
  "file_reference": {
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "type": "internal"
  },
  "descriptions": [
    {
      "language": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
      },
      "description": "Técnicas para hacer café"
    }
  ],
  "external_id": "which-brewing-fits-you",
  "last_modified": "2017-09-12T08:29:36.1645977Z"
}
{
  "request_id": "00000000-0000-0000-1614-0080000000cd",
  "error_code": 5,
  "message": "The provided request body is invalid. See the 'validation_errors' attribute for more information and specify a valid JSON object.",
  "validation_errors": [
    {
      "message": "Required property 'description' not found in JSON. Path 'descriptions[0]', line 7, position 6.",
      "path": "descriptions[0]",
      "line": 7,
      "position": 6
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

asset_external_id
string
required

The external ID of the new asset. Use this parameter as a custom unique identifier for your assets. Note that you cannot upsert external ID into already existing assets within the Kentico Cloud project. Example: which-brewing-fits-you.

Body Params

file_reference
object
required

The reference to the binary file. This parameter is only required when creating a new asset.

file_reference.id
string
required

The ID of the referenced binary file. Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c.

file_reference.type
string
required

The type of the reference. Example: internal.

title
string

The title of the new asset. Maximum length is 50 characters. Use this parameter to better identify and filter your assets in the UI. Example: Coffee Brewing Techniques.

descriptions
array of objects
required

An array of asset descriptions.

 

Returns

If the request was successful, the API returns a 200 OK HTTP status code along with the modified or created asset object.

The API returns a 400 Bad Request when any of the following occurs:

  • The descriptions attribute is missing, invalid, or contains invalid asset description objects.
  • the title attribute is longer than 50 characters.
  • The value of the external_id attribute does not match the external ID specified in the URL.
  • The request is malformed.
Suggest Edits

Delete an asset

Removes an unused asset specified by its internal ID or external ID.

 
deletehttps://manage.kenticocloud.com/v1/projects/project_id/assets/asset_identifier
curl --request DELETE \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/fcbb12e6-66a3-4672-85d9-d502d16b8d9c \
# --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/external-id/which-brewing-fits-you \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
using KenticoCloud.ContentManagement;

ContentManagementOptions options = new ContentManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
};

ContentManagementClient client = new ContentManagementClient(options);

AssetIdentifier identifier = AssetIdentifier.ById(Guid.Parse("fcbb12e6-66a3-4672-85d9-d502d16b8d9c"));
// AssetIdentifier identifier = AssetIdentifier.ByExternalId("which-brewing-fits-you");

await client.DeleteAssetAsync(identifier);
A binary file was returned

You couldn't be authenticated

 
{
  "request_id": "00000000-0000-0000-6f12-0080000000c7",
  "error_code": 105,
  "message": "The requested asset 'fcbb12e6-66a3-4672-85d9-d502d16b8d9c' was not found."
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

asset_identifier
string
required

An identifier of a specific asset. You can identify the asset by its internal ID (fcbb12e6-66a3-4672-85d9-d502d16b8d9c) or its external ID (external-id/which-brewing-fits-you).

 

Returns

If the request was successful, the specified asset is deleted from the project and the API returns a 204 HTTP status code. When called on a non-existent or already deleted asset, the API responds with a 404 HTTP status code.

Suggest Edits

Project report model

Object model description of the project report model.

 

After importing your content in Kentico Cloud, you can validate the whole project to find out whether there are any issues within the imported content.

A project validity report contains a list of issues found in language variants of all content items. The issues can indicate that either certain content elements reference non-existing objects or contain values that do not meet the limitations set by a content type.

Project report model

Attribute Description Type Notes
project Information about the specified project Project object
variant_issues Report of the problems found in the project array of Variant issue objects

Project object

The project object contains the project ID and display name.

Attribute Description Type
id The ID of the project string
name The display name of the project string

Variant issue object

The variant_issues attribute is an array of issues found in the project. Each variant issue object contains information necessary to identify the language variant (content item and project language metadata) and lists the content elements.

Attribute Description Type
item Information about the content item Content item metadata object
language Information about the project language Language metadata object
issues Information about issues found in specific content elements array of Content element issue objects

Variant issue – Content item metadata

Attribute Description Type
id ID of the content item string
name Display name of the content item string
codename Codename of the content item string

Variant issue – Language metadata

Attribute Description Type
id ID of the project language string
name Display name of the project language string
codename Codename of the project language string

Variant issue – Content element issue

For each issue found in a specific language variant, the issues array will contain a content element issue with metadata about the content element and an array of validation messages describing the problem.

A note on terminology in messages: A "content module" is a content item referenced in Linked items or Rich text elements. See Linked content and components for more details.

Attribute Description Type
element Information about the content element Content element metadata object
messages Validation messages for the content element array of strings

Variant issue – Content element metadata

Attribute Description Type
id ID of the element string
name Display name of the element string
codename Codename of the element string

Example: Validity report object

{
  "project": {
    "id": "975bf280-fd91-488c-994c-2f04416e5ee3",
    "name": "Sample Project"
  },
  "variant_issues": [
    {
      "item": {
        "id": "b2fea94c-73fd-42ec-a22f-f409878de187",
        "name": "Origins of Arabica Bourbon",
        "codename": "origins_of_arabica_bourbon"
      },
      "language": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "English (United States)",
        "codename": "en-US"
      },
      "issues": [
        {
          "element": {
            "id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
            "name": "Related articles",
            "codename": "related_articles"
          },
          "messages": [
            "Element 'Related articles' contains a content module Colombia Carlos Imbachi of type Coffee that is not allowed in this context."
          ]
        }
      ]
    },
    {
      "item": {
        "id": "cf106f4e-30a4-42ef-b313-b8ea3fd3e5c5",
        "name": "Coffee Beverages Explained",
        "codename": "coffee_beverages_explained"
      },
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8",
        "name": "Spanish (Spain)",
        "codename": "es-ES"
      },
      "issues": [
        {
          "element": {
            "id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
            "name": "Related articles",
            "codename": "related_articles"
          },
          "messages": [
            "Element 'Related articles' is required but has no value",
            "Element 'Related articles' should have at least 1 content module(s) but has 0 content module(s)."
          ]
        },
        {
          "element": {
            "id": "b9dc537c-2518-e4f5-8325-ce4fce26171e",
            "name": "Meta description",
            "codename": "meta_description"
          },
          "messages": [
            "Element 'Meta description' should have at most 160 characters(s) but has 174 character(s)."
          ]
        }
      ]
    }
  ]
}
Suggest Edits

Validate project content

Checks your project's content items for issues, such as:

  • Content elements referencing non-existing objects.
  • Values of certain content elements not meeting the limitations set in content types.

We recommend that you use this endpoint after successfully importing content into your project.

 
posthttps://manage.kenticocloud.com/v1/projects/project_id/validate
curl --request POST \
  --url https://manage.kenticocloud.com/v1/projects/975bf280-fd91-488c-994c-2f04416e5ee3/validate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "project": {
    "id": "975bf280-fd91-488c-994c-2f04416e5ee3",
    "name": "Sample Project"
  },
  "variant_issues": [
    {
      "item": {
        "id": "b2fea94c-73fd-42ec-a22f-f409878de187",
        "name": "Origins of Arabica Bourbon",
        "codename": "origins_of_arabica_bourbon"
      },
      "language": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "English (United States)",
        "codename": "en-US"
      },
      "issues": [
        {
          "element": {
            "id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
            "name": "Related articles",
            "codename": "related_articles"
          },
          "messages": [
            "Element 'Related articles' contains a content module Colombia Carlos Imbachi of type Coffee that is not allowed in this context."
          ]
        }
      ]
    },
    {
      "item": {
        "id": "cf106f4e-30a4-42ef-b313-b8ea3fd3e5c5",
        "name": "Coffee Beverages Explained",
        "codename": "coffee_beverages_explained"
      },
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8",
        "name": "Spanish (Spain)",
        "codename": "es-ES"
      },
      "issues": [
        {
          "element": {
            "id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
            "name": "Related articles",
            "codename": "related_articles"
          },
          "messages": [
            "Element 'Related articles' is required but has no value",
            "Element 'Related articles' should have at least 1 content module(s) but has 0 content module(s)."
          ]
        },
        {
          "element": {
            "id": "b9dc537c-2518-e4f5-8325-ce4fce26171e",
            "name": "Meta description",
            "codename": "meta_description"
          },
          "messages": [
            "Element 'Meta description' should have at most 160 characters(s) but has 174 character(s)."
          ]
        }
      ]
    }
  ]
}

Path Params

project_id
string
required

The ID of your project.

 

Returns

A project report summarizing the issues found in the language variants of the specified project.

Suggest Edits

Migration API

 

Discontinuation notice

The Migration API will be fully operational until December 31, 2018. After this date, the API will stop working for all Kentico Cloud accounts. We recommend using the Content Management API instead.

The Kentico Cloud Migration API is a read-only REST API. The API is available only for Kentico Cloud projects stored in the West US data center.

The base URL for all requests is https://api.kenticocloud.com/draft/projects.

You can use the Migration API to import finished content items into a CMS of your choice, or perform a one-time export of larger amounts of content from Kentico Cloud.

Note: If you need to frequently deliver content, filter it and leverage content caching, we recommend using the Delivery API instead.

Suggest Edits

List projects

Retrieve a list of the projects available to you.

 
gethttps://api.kenticocloud.com/draft/projects
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "projects": [
    {
      "project_id": "917bb277-c013-45b9-a6fb-6ca925578f41",
      "name": "Empty Project"
    },
    {
      "project_id": "38af179c-40ba-42e7-a5ca-33b8cdcc0d45",
      "name": "Sample Project"
    }
  ]
}
 

Returns

A list of projects you have access to based on the provided API key in the Authorization header.

Suggest Edits

List content items

Retrieve a list of content items from your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/items
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "items": [
    {
      "item_id": "d686ae55-39ea-44e5-a40b-ba97d90e4dec",
      "type_id": "a77e9845-a2d9-4573-bbae-1e0a4cb70637",
      "workflow_status_id": "8eb2388e-682b-45ae-8405-5add40430dfd",
      "name": "Scheduled maintenance 2017/02",
      "sitemap_location": [],
      "last_modified": "2017-02-13T15:16:25.9473812Z",
      "elements": [
        {
          "value": "Another maintenance",
          "element_id": "93969f59-8130-83be-24d7-b7887ccc55a5",
          "name": "Title",
          "type": "text"
        },
        {
          "value": "<h1>Scheduled maintenance</h1>\n<p>Remember, we're doing this for you. It's going to be fine.</p>",
          "element_id": "c222f15f-a72f-3570-574a-975c21036920",
          "name": "Announcement text",
          "type": "rich_text"
        },
        {
          "value": [],
          "element_id": "c460263c-38b4-baff-5349-6440aae49716",
          "name": "Banner",
          "type": "asset"
        }
      ]
    },
    {
      "item_id": "307ba686-a05b-4678-b5ce-bff6fc558d27",
      "type_id": "a77e9845-a2d9-4573-bbae-1e0a4cb70637",
      "workflow_status_id": "8eb2388e-682b-45ae-8405-5add40430dfd",
      "name": "Scheduled maintenance 2017/04",
      "sitemap_location": [],
      "last_modified": "2017-02-13T15:00:18.8425411Z",
      "elements": [
        {
          "value": "Scheduled maintenance 2017/04",
          "element_id": "93969f59-8130-83be-24d7-b7887ccc55a5",
          "name": "Title",
          "type": "text"
        },
        {
          "value": "<h1>Scheduled maintenance</h1>\n<p>You can expect a temporary downtime in two months.&nbsp;</p>",
          "element_id": "c222f15f-a72f-3570-574a-975c21036920",
          "name": "Announcement text",
          "type": "rich_text"
        },
        {
          "value": [],
          "element_id": "c460263c-38b4-baff-5349-6440aae49716",
          "name": "Banner",
          "type": "asset"
        }
      ]
    }
  ],
  "pagination": {
    "total_item_count": 2,
    "page_item_count": 2,
    "page_count": 1,
    "current_page": 1
  }
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

Query Params

sitemap_location
string

Filter the retrieved content items by their location in the project's sitemap. You can use this parameter multiple times to get items from several locations at once. Example: 9ee4e597-40c3-266d-5965-8d3e437b8eed. To retrieve a list of sitemap location IDs, see List sitemap locations.

workflow_status
string

Filter the retrieved content items by their workflow step. This way you can get, for example, only the approved content items by providing the ID of the specific workflow step. Example: 65e025db-1a04-4b9d-b366-408e09b58cb7. To retrieve a list of workflow status IDs, see List workflow steps.

content_type
string

Filter the retrieved content items by their content type. Example: 2e9b7cdd-e623-4918-a3f0-eb237878723c. To retrieve a list of content type IDs, see List content types.

 

Returns

An array of content item objects available in the specified project.

Suggest Edits

List content types

Retrieve a list of content types available in your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/types
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/types' \
--header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "types": [
    {
      "type_id": "b2c14f2c-6467-460b-a70b-bca17972a33a",
      "name": "About us",
      "elements": [
        {
          "element_id": "cff560dc-ed24-7036-cbb6-b7a1b61b196a",
          "name": "Facts",
          "type": "modular_content"
        }
      ]
    },
    {
      "type_id": "d9748663-f567-4c51-a922-c24a1d6b935a",
      "name": "Accessory",
      "elements": [
        {
          "element_id": "f9e2672c-5035-412e-3985-d6112b3781bd",
          "name": "Product name",
          "type": "text"
        },
        {
          "element_id": "51d63ac3-d40d-15ea-c219-be207714077c",
          "name": "Price",
          "type": "number"
        },
        {
          "element_id": "f0db12e6-86e4-8597-903b-c5984076d6b3",
          "name": "Image",
          "type": "asset"
        },
        {
          "element_id": "ab75ff46-b629-5ce5-aac9-79ed8a7b869c",
          "name": "Manufacturer",
          "type": "text"
        },
        {
          "taxonomy_group_id": "79b1c5b6-30bc-d076-a236-d9ec9f1ff01b",
          "element_id": "ef13b1f4-b558-f707-35a4-86146dbe4518",
          "name": "Product status",
          "type": "taxonomy"
        },
        {
          "element_id": "9740e2d0-87e8-52f5-ff4c-566fa00b1253",
          "name": "Short description",
          "type": "rich_text"
        },
        {
          "element_id": "1f961774-a589-4e21-9f8e-a8c4908ea476",
          "name": "Long description",
          "type": "rich_text"
        }
      ]
    },
    {
      "type_id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89",
      "name": "Article",
      "elements": [
        {
          "taxonomy_group_id": "f30c7f72-e9ab-8832-2a57-62944a038809",
          "element_id": "0a16b642-ac3e-584d-a45a-ba354a30b2bd",
          "name": "Personas",
          "type": "taxonomy"
        },
        {
          "element_id": "85d5efc6-f47e-2fde-a6f5-0950fe89ecd1",
          "name": "Title",
          "type": "text"
        },
        {
          "element_id": "62eb9881-e222-6b81-91d2-fdf052726414",
          "name": "Teaser image",
          "type": "asset"
        },
        {
          "element_id": "4ae5f7a9-fe1f-1e8c-bfec-d321455139c4",
          "name": "Post date",
          "type": "date_time"
        },
        {
          "element_id": "90550cbe-7bff-40a9-2947-9c81489fe562",
          "name": "Summary",
          "type": "text"
        },
        {
          "element_id": "108ed7c0-fc8c-c0ec-d0b5-5a8071408b54",
          "name": "Body Copy",
          "type": "rich_text"
        },
        {
          "element_id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
          "name": "Related articles",
          "type": "modular_content"
        },
        {
          "element_id": "5efb2425-5987-a4a6-a2d3-b14712b56e73",
          "name": "Meta keywords",
          "type": "text"
        },
        {
          "element_id": "b9dc537c-2518-e4f5-8325-ce4fce26171e",
          "name": "Meta description",
          "type": "text"
        }
      ]
    },
    {
      "type_id": "e097306b-3893-4a42-9973-2525fad14d66",
      "name": "Office",
      "elements": [
        {
          "element_id": "bb81a11d-886c-2a32-e480-29f01cea667f",
          "name": "Name",
          "type": "text"
        },
        {
          "element_id": "f7eb7ab2-4e41-aca0-7e93-dbbbdca330eb",
          "name": "Street",
          "type": "text"
        },
        {
          "element_id": "95477abc-d6b4-a6b3-5b72-c92763da55bf",
          "name": "City",
          "type": "text"
        },
        {
          "element_id": "4fbc7779-652d-7716-2673-7419aaaceed1",
          "name": "Country",
          "type": "text"
        },
        {
          "element_id": "08df2f10-52b8-d451-fab1-b6da8ddb3fd2",
          "name": "State",
          "type": "text"
        },
        {
          "element_id": "e7141da8-8792-a66d-d1c8-1fe704758393",
          "name": "Zip code",
          "type": "text"
        },
        {
          "element_id": "2ac708e2-cd0e-67b0-67f8-71725625dc6d",
          "name": "Phone",
          "type": "text"
        },
        {
          "element_id": "251dc38f-43a3-d924-a328-8708ecb00ef1",
          "name": "Email",
          "type": "text"
        }
      ]
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

 

Returns

An array of content type objects available in the specified project.

Suggest Edits

View a content item

Retrieve a specific content item from your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/items/item_id
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/baccdc8b-7dd1-40ea-98bb-6a992b0558df' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "item_id": "baccdc8b-7dd1-40ea-98bb-6a992b0558df",
  "type_id": "929985ac-4aa5-436b-85a2-94c2d4fbbebd",
  "workflow_status_id": "13145328-b946-4e47-9c9d-6f40c7aaeaef",
  "name": "Colombia Carlos Imbachi",
  "sitemap_location": [
    "c6e04208-d6dd-1e25-f7ac-526daf042fb6"
  ],
  "last_modified": "2017-03-02T12:20:25.450198Z",
  "elements": [
    {
      "value": "Colombia Carlos Imbachi",
      "element_id": "edaec5c4-e653-9109-eb0d-fc40ccf3c810",
      "name": "Product name",
      "type": "text"
    },
    {
      "value": 10.5,
      "element_id": "624592dc-49b2-330a-7185-e1f2396ce90c",
      "name": "Price",
      "type": "number"
    },
    {
      "value": [
        {
          "asset_id": "80ee78c2-e6cb-4898-8053-91be9e763a4c",
          "name": "colombia.jpg",
          "type": "image/jpeg",
          "size": 75568,
          "last_modified": "2016-09-01T08:38:07.3800056Z",
          "create_download_link": "https://api.kenticocloud.com/draft/projects/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/assets/80ee78c2-e6cb-4898-8053-91be9e763a4c"
        }
      ],
      "element_id": "30ac3ccc-1e7f-1490-e1f6-915c64176a55",
      "name": "Image",
      "type": "asset"
    },
    {
      "value": "<p>The Colombian gold in the form of top quality coffee, also recognizable&nbsp;for its character. &nbsp;</p>",
      "images": [],
      "element_id": "b5a3263a-a1d7-92b7-865a-329f833285fa",
      "name": "Short description",
      "type": "rich_text"
    },
    {
      "value": "<p>As a part of our farmer-direct Colombia program, we bring you a special (above 88!) farm-specific number. We had some very special cupping samples sent to us straight from Colombia. And although they were all fantastic, this one really stood out from the others. Previously, we offered the \"First Place SCAA Coffee of the Year\" Carlos Imbachi. Just so you know what we're on about here, the famous Panama Esmeralda Especial Gesha ended up in 2nd place to Carlos Imbachi. Take this as another testament to the greatness and potential of Colombian coffee.</p>\n<figure data-image-id='9em8m'><img src=\"#\" alt=\"Colombia coffee\" data-image-id='9em8m'></figure><p>One cupping of this specialty was enough to recognize the unprecedented quality and character of this coffee. Mr. Imbachi's farm is located in the San Augustin region of Hulia, where he grows this coffee at an altitude of 5,700 feet.&nbsp;</p>",
      "images": [
        {
          "_id": "c52f0f99-d9bd-2598-d171-c37ab256fb7e",
          "asset": {
            "asset_id": "47b57724-b689-4865-9f12-521ddef2d025",
            "name": "kentico_cloud_rgb_small.png",
            "type": "image/png",
            "size": 8209,
            "last_modified": "2017-02-13T14:04:09.2146055Z",
            "create_download_link": "https://api.kenticocloud.com/draft/projects/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/assets/47b57724-b689-4865-9f12-521ddef2d025"
          }
        },
        {
          "_id": "9em8m",
          "asset": {
            "asset_id": "13e3857f-1fbb-4ec0-b7ec-3829d0325069",
            "name": "colombia.jpg",
            "type": "image/jpeg",
            "size": 75568,
            "last_modified": "2017-03-02T12:17:52.0565686Z",
            "create_download_link": "https://api.kenticocloud.com/draft/projects/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/assets/13e3857f-1fbb-4ec0-b7ec-3829d0325069"
          }
        }
      ],
      "element_id": "d468a0aa-e0fa-0cae-41db-6e006bff2527",
      "name": "Long description",
      "type": "rich_text"
    },
    {
      "value": [],
      "element_id": "1ee64175-fde7-fc1e-5259-511a31c326c3",
      "name": "Product status",
      "type": "taxonomy"
    },
    {
      "value": "Finca Buenavista - Carlos Imbachi",
      "element_id": "e5cf103f-9b84-1ab0-29f1-fb5a1657c6f7",
      "name": "Farm",
      "type": "text"
    },
    {
      "value": "Colombia",
      "element_id": "6eec1918-378d-3b15-8b1a-19c5f0748321",
      "name": "Country",
      "type": "text"
    },
    {
      "value": "Caturra",
      "element_id": "301c6712-962f-b05a-6f6e-2f0e1e959039",
      "name": "Variety",
      "type": "text"
    },
    {
      "options": [
        "41cc0828-8a1c-3714-f86c-dee5faf09f1c"
      ],
      "element_id": "d5a32749-c934-e502-3e02-5512115735ce",
      "name": "Processing",
      "type": "multiplechoice"
    },
    {
      "value": "5700",
      "element_id": "23a772c0-0b2b-588d-9849-e29068701f03",
      "name": "Altitude",
      "type": "text"
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

item_id
string
required

The ID of the content item. Example: baccdc8b-7dd1-40ea-98bb-6a992b0558df.

 

Returns

A single content item object if a valid content item ID was specified.

Suggest Edits

List workflow steps

Retrieve a list of workflow steps in your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/workflow
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/workflow' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "statuses": [
    {
      "workflow_id": "88ac5e6e-1c5c-4638-96e1-0d61221ad5bf",
      "name": "Draft",
      "color": "red"
    },
    {
      "workflow_id": "13145328-b946-4e47-9c9d-6f40c7aaeaef",
      "name": "Review",
      "color": "yellow"
    },
    {
      "workflow_id": "48de7f2d-80de-4a8e-9efb-fc23bffbf75a",
      "name": "SEO verification",
      "color": "lime"
    },
    {
      "workflow_id": "99435d07-a9b7-4273-b439-a6e4bc125140",
      "name": "Ready for approval",
      "color": "teal"
    },
    {
      "workflow_id": "a1b9efa3-8270-47e4-8d8d-b182710d1e3b",
      "name": "Approved",
      "color": "blue"
    },
    {
      "workflow_id": "b4363ccd-8f21-45fd-a840-5843d7b7f008",
      "name": "Published",
      "color": "light-green"
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

 

Returns

A list of workflow steps defined in the specified project.

Suggest Edits

List sitemap locations

Retrieve a list of sitemap locations in your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/sitemap
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/sitemap' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "nodes": [
    {
      "sitemap_node_id": "778dd673-a341-41db-0735-a9d6bcede0b3",
      "name": "Home",
      "children": []
    },
    {
      "sitemap_node_id": "820563dc-6738-c641-cdd5-18fdcbebff9b",
      "name": "Products",
      "children": [
        {
          "sitemap_node_id": "c6e04208-d6dd-1e25-f7ac-526daf042fb6",
          "name": "Coffee",
          "children": []
        },
        {
          "sitemap_node_id": "0b7a84cd-8547-504e-b1aa-1ae8f7b6b675",
          "name": "Brewers",
          "children": []
        },
        {
          "sitemap_node_id": "fedea22c-4ab7-908e-6ac0-85b9730e3a6c",
          "name": "Accessories",
          "children": []
        },
        {
          "sitemap_node_id": "8fdb2025-e240-1a17-df13-b5914a681730",
          "name": "Grinders",
          "children": []
        }
      ]
    },
    {
      "sitemap_node_id": "a60fe91c-88ea-6990-fe3b-cf8f8504cd33",
      "name": "Cafes",
      "children": [
        {
          "sitemap_node_id": "6f648389-3bce-43ec-2529-e5ff3e12ebe7",
          "name": "North America",
          "children": []
        },
        {
          "sitemap_node_id": "ef86a740-9e4c-0b33-4275-ae78558e71a7",
          "name": "Europe",
          "children": []
        },
        {
          "sitemap_node_id": "98c9e0f1-b6f7-510d-522a-0d39fc62aa1a",
          "name": "Australia",
          "children": []
        }
      ]
    },
    {
      "sitemap_node_id": "45a123f3-1c55-c697-7dae-78369c8f1e2c",
      "name": "Articles",
      "children": []
    },
    {
      "sitemap_node_id": "22110d88-4b92-32a0-db61-9b8dbe401920",
      "name": "Offices",
      "children": []
    },
    {
      "sitemap_node_id": "398551ec-3f19-b177-2661-69bed4f35e20",
      "name": "About us",
      "children": []
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

 

Returns

A list of sitemap locations defined in the specified project. The API returns the complete sitemap hierarchy with all child sitemap locations.

Suggest Edits

List taxonomy groups

Retrieve a list of taxonomy groups in your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/taxonomy
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/taxonomy' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "taxonomy_groups": [
    {
      "taxonomy_id": "79b1c5b6-30bc-d076-a236-d9ec9f1ff01b",
      "name": "Product status",
      "nodes": [
        {
          "taxonomy_node_id": "6352c8bf-8024-9986-8373-35445e1f0d59",
          "name": "On sale",
          "children": []
        },
        {
          "taxonomy_node_id": "8d808da3-29de-e608-5699-8565687dd474",
          "name": "Bestseller",
          "children": []
        }
      ]
    },
    {
      "taxonomy_id": "f30c7f72-e9ab-8832-2a57-62944a038809",
      "name": "Personas",
      "nodes": [
        {
          "taxonomy_node_id": "6693ca6e-79e0-57e4-000d-d23d5ce8f656",
          "name": "Coffee expert",
          "children": [
            {
              "taxonomy_node_id": "6a372f43-ccd7-e524-6308-c2094e7b6596",
              "name": "Barista",
              "children": []
            },
            {
              "taxonomy_node_id": "cdf2f3c6-89e3-5df1-f7de-7179460bd6b4",
              "name": "Cafe owner",
              "children": []
            }
          ]
        },
        {
          "taxonomy_node_id": "ab2b73a3-473d-4232-0652-495598f5d670",
          "name": "Coffee enthusiast",
          "children": [
            {
              "taxonomy_node_id": "208a9095-1b92-10da-7627-75ae311935cf",
              "name": "Coffee lover",
              "children": []
            },
            {
              "taxonomy_node_id": "4fa27320-c363-3ebe-5ab5-b531300f053f",
              "name": "Coffee blogger",
              "children": []
            }
          ]
        }
      ]
    }
  ]
}

Path Params

project_id
string
required

The ID of your project. Example: 975bf280-fd91-488c-994c-2f04416e5ee3.

 

Returns

A list of taxonomy groups for the specified project with the taxonomy items each group contains.