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>/
Deliver content from Kentico Cloud to your web applications and mobile applications. Learn more.
Personalization API https://engage-api.kenticocloud.com/v1/visitor/<VISITOR_UID>/ Optimize visitors' experience when visiting your website. Learn more.
Migration API https://api.kenticocloud.com/draft/ Migrate content and content models from Kentico Cloud to a platform of your choice. Learn more.
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. Learn more
Tracking API https://engage-ket.kenticocloud.com/api/v1/track/<YOUR_PROJECT_ID>/ Track your visitors or users from anywhere through a REST API. Learn more.

Trying out the endpoints

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

Try any of the API endpoints in this reference.

Try any of the API endpoints in this reference.

Suggest Edits

Authentication

How and when to authenticate your requests.

 

Authenticate requests to the Kentico Cloud APIs by using API keys. You can find the keys in Kentico Cloud when you 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:

  • Delivery Preview API – https://preview-deliver.kenticocloud.com/<YOUR_PROJECT_ID>/
  • Personalization APIhttps://engage-api.kenticocloud.com/v1/visitor/VISITOR_UID/
  • Content Management APIhttps://manage.kenticocloud.com/projects/<YOUR_PROJECT_ID>
  • Migration APIhttps://api.kenticocloud.com/draft/projects

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 HTTP over TLS 1.2.

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 from your project using the production URL:
https://deliver.kenticocloud.com/<YOUR_PROJECT_ID>/

Preview unpublished content from your project using the preview URL:
https://preview-deliver.kenticocloud.com/<YOUR_PROJECT_ID>/

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

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 content items used in Modular content and Rich text elements 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
  },
  "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.

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

Filtering by system values

To filter by a system attribute, you need to use a query parameter in the system.<attribute_name> format. Valid 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 an element value, 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.

For example, query system.type=article&system.sitemap_locations[contains]=cafes will return all 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 equals the specified value.

system.type=article
system.language=de-DE

Simple types

[lt]

Attribute value is less than the specified value.

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

Simple types

[lte]

Attribute value is less than or equals the specified value.

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

Simple types

[gt]

Attribute value is greater than the specified value.

system.last_modified[gt]=2016
elements.price[gt]=1000

Simple types

[gte]

Attribute value is greater than or equals the specified value.

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

Simple types

[range]

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

system.last_modified[range]=2017-02,2017-03
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] filters only with arrays. Array attributes in Kentico Cloud include the sitemap locations system object, and the Modular content, Multiple choice, and Taxonomy elements. All the other system attributes and content type elements are represented as simple types, i.e., strings, numbers, or 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 which parts of content to retrieve.

 

You can retrieve only certain elements from a content item by using the elements query parameter. For example, to retrieve only the elements with codenames title, summary, and related_articles, you can use elements=title,summary,related_articles as a query parameter.

Note: You cannot omit the System object from the JSON response using any query.

Suggest Edits

Modular content

 

Content items might reference modular content items using the Modular content element. Recursively, these modular content items can reference another modular content items. By default, only one level of modular content is returned.

  • If you want to include more than one level of modular content items in response, use the depth query parameter.
  • If you want to exclude all modular content, use the depth=0 query parameter.
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 { DeliveryClient, TypeResolver, DeliveryClientConfig, SortOrder } from 'kentico-cloud-delivery-typescript-sdk';

// Create strongly typed models according to https://github.com/Enngage/KenticoCloudDeliveryTypeScriptSDK#creating-models
var typeResolvers = [
    new TypeResolver("article", () => new Article())
];
var config = new DeliveryClientConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers);
var deliveryClient = new DeliveryClient(config);

deliveryClient.items<Article>()
    .equalsFilter('system.type', 'article')
    .elementsParameter(['title', 'summary', 'post_date', 'teaser_image'])
    .orderParameter('elements.post_date', SortOrder.desc)
    .limitParameter(3)
    .get()
    .subscribe(response => console.log(response.items));
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);
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.kenticocloud.com:443/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.kenticocloud.com:443/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 contain Modular content elements and reference other content items. By default, only the first level of modular content is returned. If you need to exclude all modular content from the response, set the parameter to 0.

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 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
item Content item data collection of the system and elements attributes
system System attributes of the content item System
elements Content type elements in the content item collection of Element objects
modular_content A list of content items used in Modular content and Rich text elements collection of Content item objects

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
  }
}
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 { DeliveryClient, TypeResolver, DeliveryClientConfig } from 'kentico-cloud-delivery-typescript-sdk';

// Create strongly typed models according to https://github.com/Enngage/KenticoCloudDeliveryTypeScriptSDK#creating-models
var typeResolvers = [
    new TypeResolver("article", () => new Article())
];
var config = new DeliveryClientConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers);
var deliveryClient = new DeliveryClient(config);

deliveryClient.item<Article>('on_roasts')
    .elementsParameter(['title', 'summary', 'post_date', 'teaser_image'])
    .depthParameter(1)
    .get()
    .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);
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.kenticocloud.com:443/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": {
    # list of related Content items
  }
}

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 contain Modular content elements and reference other content items. By default, only the first level of modular content is returned. If you need to exclude all modular content from the response, set the parameter to 0.

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, TypeResolver, DeliveryClientConfig } from 'kentico-cloud-delivery-typescript-sdk';

var config = new DeliveryClientConfig("975bf280-fd91-488c-994c-2f04416e5ee3", []]);
var deliveryClient = new DeliveryClient(config);

deliveryClient.types()
    .limitParameter(3)
    .get()
    .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);
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
system System attributes of the content type System
elements Content type elements in the content item collection of Element objects

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, TypeResolver, DeliveryClientConfig } from 'kentico-cloud-delivery-typescript-sdk';

var config = new DeliveryClientConfig("975bf280-fd91-488c-994c-2f04416e5ee3", []]);
var deliveryClient = new DeliveryClient(config);

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

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

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

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

Besides formatted text in the element's value attribute, Rich text elements can contain inline images and links to other content items.

Images (single object)

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

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.

Modular content

A list of content items inserted into rich text as modules. The list is represented as an array of strings, each string being a codename of a content item.

"description": {
  "type": "rich_text",
  "name": "Description",
  "images": {
    "14mio": {
      "image_id": "14mio",
      "description": "Roasting coffee beans",
      "url": "https://assets.kenticocloud.com:443/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"
  ],
  "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.kenticocloud.com:443/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>"
}
"description": {
  "type": "rich_text",
  "name": "Description"
}

Multiple choice

The value of a Multiple choice element is an array of option objects. Each option object has a name and codename.

"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

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

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

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.

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.kenticocloud.com:443/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/e700596b-03b0-4cee-ac5c-9212762c027a/coffee-beverages-explained-1080px.jpg"
    }
  ]
}
"teaser_image": {
  "type": "asset",
  "name": "Teaser image"
}

Modular content

The relations to content items saved in a Modular content element are represented as an array of strings. Each string being a codename of a content item.

"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 the codename of itself 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, TypeResolver, DeliveryClientConfig } from 'kentico-cloud-delivery-typescript-sdk';

var config = new DeliveryClientConfig("975bf280-fd91-488c-994c-2f04416e5ee3", []);
var deliveryClient = new DeliveryClient(config);

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

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

Element element = client.getContentTypeElement("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, TypeResolver, DeliveryClientConfig } from 'kentico-cloud-delivery-typescript-sdk';

var config = new DeliveryClientConfig("975bf280-fd91-488c-994c-2f04416e5ee3", []);
var deliveryClient = new DeliveryClient(config);

deliveryClient.taxonomies()
    .limitParameter(3)
    .get()
    .subscribe(response => console.log(response.taxonomy));
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);
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 group = await client.GetTaxonomyGroupAsync("personas");
import { DeliveryClient, TypeResolver, DeliveryClientConfig } from 'kentico-cloud-delivery-typescript-sdk';

var config = new DeliveryClientConfig("975bf280-fd91-488c-994c-2f04416e5ee3", []]);
var deliveryClient = new DeliveryClient(config);

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

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

TaxonomyGroup taxonomyGroup = client.getTaxonomyGroup("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

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

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": "9b4525f5-4eed-4672-a70f-7a559be5a1fb",
    "type": "taxonomy",
    "operation": "upsert",
    "api_name": "delivery_production",
    "project_id": "217935db-822a-43ac-9657-f33c10d318e7"
  },
  "data": {
    "items": [
      {
        "language": "en-US",
        "codename": "which_brewing_fits_you_",
        "type": "article"
      },
      {
        "language": "es-ES",
        "codename": "on_roasts",
        "type": "article"
      },
      {
        "language": "en-US",
        "codename": "on_roasts",
        "type": "article"
      },
      {
        "language": "es-ES",
        "codename": "coffee_beverages_explained",
        "type": "article"
      },
      {
        "language": "en-US",
        "codename": "coffee_beverages_explained",
        "type": "article"
      },
      {
        "language": "en-US",
        "codename": "coffee_processing_techniques",
        "type": "article"
      }
    ],
    "taxonomies": [
      {
        "codename": "personas"
      }
    ]
  }
}
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 represents a data model in Kentico Cloud. You can receive notifications for changes to the following:

Type Description Possible operations
asset An asset from the project's Asset library upsert
content_item A content item archive, restore, publish, unpublish, upsert
content_item_variant A content item variant archive, restore, publish, unpublish, upsert
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

Operations are actions that can be performed on types.

Operation Description Applies to types
archive A data model was deleted content_item, taxonomy
restore A data model was restored content_item, 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_item_variant, content_type, sitemap, taxonomy
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("UTF-8"), "HmacSHA256");
    sha256Hmac.init(secretKeySpec);

    return DatatypeConverter.printHexBinary(sha256Hmac.doFinal(message.getBytes("UTF-8"))).toLowerCase();
}
Suggest Edits

Personalization API

 

The Kentico Cloud Personalization API is read-only. You can retrieve data about your visitors but not add or modify it.

The base URL for all requests is https://engage-api.kenticocloud.com/v1/visitor/<VISITOR_UID>/.

All requests to the API must be authenticated by including an authorization header containing your Personalization API Key. See Authentication for more details.

curl --request GET \
  --url https://engage-api.kenticocloud.com/v1/visitor/e3e9e191a12b9257/UsualLocation \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json'

User and session ID

All Personalization API methods require a user ID, which defines ID of a specific visitor on your website. Methods retrieving data about current visitor behavior also require a session ID. You can get these values either by parsing content of a cookie stored by the tracking code in your browser or by calling a JavaScript method in your website (this is the recommended way).

You can call the JavaScript function ket(...) defined in global scope.

  • User ID – call ket('getUid', function(uid){ console.log('UID: ' + uid); }); in your browser console.
  • Session ID – call ket('getSid', function(sid){ console.log('SID: ' + sid); }); in your browser console.

Both methods use a callback with string argument containing an ID of your website. Use the values when building a link to the REST interface.

Suggest Edits

Location object

Data model description of a visitor location object

 

When retrieving a visitor's current or usual location, the Personalization API returns a location object with the following attributes:

Attribute
Description
Type
Notes

city

City

string

state

State or region

string

For countries that don't have states, the attribute contains the name of the region. See examples on the right sidebar.

country

Country

string

Example location object

{
  "city": "Boston",
  "state": "Massachusetts",
  "country": "USA"
}
{
  "city": "Edinburgh", 
  "state": "Scotland",
  "country": "United Kingdom"
}
{
  "city": "Brno",
  "state": "South Moravian",
  "country": "Czechia"
}
Suggest Edits

View usual visitor location

Retrieve the location from which the specified visitor most usually connects to your website.

 
gethttps://engage-api.kenticocloud.com/v1//visitor/uid/usuallocation
curl --request GET \
  --url https://engage-api.kenticocloud.com/v1/visitor/e3e9e191a12b9257/UsualLocation \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json'
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;

PersonalizationClient client = new PersonalizationClient("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14");

string uid = this.Request.GetCurrentPersonalizationUid();

LocationResponse location = await client.GetVisitorUsualLocationAsync(uid);
A binary file was returned

You couldn't be authenticated

{
  "city": "Boston",
  "state": "Massachusetts",
  "country": "USA"
}

Path Params

uid
string
required

The ID of a user. Example: e3e9e191a12b9257.

 

Returns

A Location object with information about the visitor's usual location based on their IP address.

Suggest Edits

View current visitor location

Retrieve the current location of the specified visitor based on their session ID.

 
gethttps://engage-api.kenticocloud.com/v1//visitor/uid/currentlocation
curl --request GET \
  --url 'https://engage-api.kenticocloud.com/v1/visitor/e3e9e191a12b9257/CurrentLocation?sid=900420c5d646260d' \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json'
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;

PersonalizationClient client = new PersonalizationClient("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14");

string uid = this.Request.GetCurrentPersonalizationUid();
string sid = this.Request.GetCurrentPersonalizationSid();

LocationResponse location = await client.GetCurrentLocationAsync(uid, sid);
A binary file was returned

You couldn't be authenticated

{
  "city": "Boston",
  "state": "Massachusetts",
  "country": "USA"
}

Path Params

uid
string
required

The ID of a user. Example: e3e9e191a12b9257.

Query Params

sid
string
required

The session ID of a specific user. Example: 900420c5d646260d.

 

Returns

A Location object with information about the visitor's current location based on their IP address.

Suggest Edits

Visit object

Data model description of a visit object

 

When retrieving information about a visitor's first or last visit, the Personalization API returns a visit object with the following attributes:

Attribute
Description
Type
Notes

visitDateTime

Date and time of the visit

string

ISO-8601 formatted date/time.

origin

Absolute URL of the website from which the visit originated

string

If empty, the visitor entered the website directly.

Example visit object

{
  "visitDateTime": "2017-02-14T11:24:45+00:00",
  "origin": "https://google.com/search?hl=en&q=kentico%20cloud"
}
Suggest Edits

View first visit

Retrieve the time and origin of the first visit of the specified visitor.

 
gethttps://engage-api.kenticocloud.com/v1//visitor/uid/firstvisit
curl --request GET \
  --url https://engage-api.kenticocloud.com/v1/visitor/e3e9e191a12b9257/FirstVisit \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json'
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;

PersonalizationClient client = new PersonalizationClient("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14");

string uid = this.Request.GetCurrentPersonalizationUid();

VisitResponse firstVisit = await client.GetFirstVisitAsync(uid);
A binary file was returned

You couldn't be authenticated

{
  "visitDateTime": "2017-02-14T11:24:45+00:00",
  "origin": ""
}

Path Params

uid
string
required

The ID of a user. Example: e3e9e191a12b9257.

 

Returns

A Visit object containing time and origin of the first visit.

Suggest Edits

View last visit

Retrieve the time and origin of the last visit of the specified visitor.

 
gethttps://engage-api.kenticocloud.com/v1//visitor/uid/lastvisit
curl --request GET \
  --url https://engage-api.kenticocloud.com/v1/visitor/e3e9e191a12b9257/LastVisit \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json' 
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;

PersonalizationClient client = new PersonalizationClient("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14");

string uid = this.Request.GetCurrentPersonalizationUid();

VisitResponse lastVisit = await client.GetLastVisitAsync(uid);
A binary file was returned

You couldn't be authenticated

{
  "visitDateTime": "2017-02-14T13:18:52+00:00",
  "origin": "https://google.com/search?q=kentico"
}

Path Params

uid
string
required

The ID of a user. Example: e3e9e191a12b9257.

 

Returns

A Visit object containing time and origin of the last visit.

Suggest Edits

Activity summary object

Object model description of a visitor's activity summary object.

 

When retrieving a summary of visitor's activity, the Personalization API returns an activity summary object with the following attributes:

Attribute
Description
Type
Notes

totalSessions

Total number of visitor's sessions

integer

activityTimeSpan

Total amount of time the visitor spent on your website

string

Value is in the hh:mm:ss format.

avgSessionActions

Average number of actions per session performed by the visitor

integer

Actions are defined as page visits, form submits or your own custom actions.

Example activity summary object

{
  "totalSessions": 3,
  "activityTimeSpan": "01:54:07",
  "avgSessionActions": 9
}
Suggest Edits

View visitor's activity summary

Retrieve a summary of the visitor's overall activity on your website.

 
gethttps://engage-api.kenticocloud.com/v1//visitor/uid/activitysummary
curl --request GET \
  --url https://engage-api.kenticocloud.com/v1/visitor/e3e9e191a12b9257/ActivitySummary \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json'
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;

PersonalizationClient client = new PersonalizationClient("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14");

string uid = this.Request.GetCurrentPersonalizationUid();

ActivitySummaryResponse summary = await client.GetActivitySummaryAsync(uid);
A binary file was returned

You couldn't be authenticated

{
  "totalSessions": 3,
  "activityTimeSpan": "01:54:07",
  "avgSessionActions": 9
}

Path Params

uid
string
required

The ID of a user. Example: e3e9e191a12b9257.

 

Returns

An Activity summary object.

Suggest Edits

Session object

Object model description of a session object.

 

When retrieving a visitor's current session, the Personalization API returns a session object with the following attributes:

Attribute
Description
Type
Notes

started

Date and time of the session start

string

ISO-8601 formatted date/time.

origin

Absolute URL of the website from which the visit originated

string

If empty, the visitor entered the website directly.

actions

A list of all actions performed by the visitor during the session

Collection of action objects

Action object

Attribute
Description
Type
Notes

type

Type of action

string

Contains one of 3 types of actions: PageVisit, FormSubmit or CustomAction.

pageUrl

URL of the page, where the action was performed

string

Returned without the base URL of your website. See examples on the right sidebar.

Example session object

{
  "started": "2017-04-19T14:41:46+00:00",
  "origin": "http://goat.ngrok.io/products/brazil-natural-barra-grande",
  "actions": [
    {
      "type": "PageVisit",
      "pageUrl": "/"
    },
    {
      "type": "PageVisit",
      "pageUrl": "/product-catalog/coffees"
    },
    {
      "type": "PageVisit",
      "pageUrl": "/articles"
    }
  ]
}
Suggest Edits

View visitor's current session

Retrieve information about the current session of a visitor on your website.

 
gethttps://engage-api.kenticocloud.com/v1//visitor/uid/currentsession
curl --request GET \
  --url 'https://engage-api.kenticocloud.com/v1/visitor/e3e9e191a12b9257/CurrentSession?sid=900420c5d646260d' \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json'
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;
 
PersonalizationClient client = new PersonalizationClient("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14");

string uid = this.Request.GetCurrentPersonalizationUid();
string sid = this.Request.GetCurrentPersonalizationSid();
 
SessionDetailResponse session = await client.GetCurrentSessionAsync(uid, sid);
A binary file was returned

You couldn't be authenticated

{
  "started": "2017-02-14T12:37:11+00:00",
  "origin": "https://google.com/search?q=kentico",
  "actions": [
		{
      "type": "PageVisit",
      "pageUrl": "/help/"
    },
    {
      "type": "PageVisit",
      "pageUrl": "/"
    }
  ]
}

Path Params

uid
string
required

The ID of a user. Example: e3e9e191a12b9257.

Query Params

sid
string
required

The session ID of a specific user. Example: 900420c5d646260d.

 

Returns

A Session object containing the summary of the visitor's current session.

Suggest Edits

Activity confirmation object

Object model description of a activity confirmation object.

 

When confirming a visitor's activity, the Personalization API returns a location object with the following attributes:

Attribute
Description
Type
Notes

activity

A binary indicator of whether the activity occurred

boolean

Is true if the visitor performed the specified action, otherwise false.

lastOccurrence

Date and time of the last occurrence of the action

string

ISO-8601 formatted date/time.
If the action was not performed, the attribute is not included in the response.

Example activity confirmation object

{
  "activity": true,
  "lastOccurrence": "2016-10-20T15:01:42+00:00"
}
Suggest Edits

Confirm visitor activity

Find out whether the visitor performed a specific action.

 
gethttps://engage-api.kenticocloud.com/v1//visitor/uid/visitoractions
curl --request GET \
  --url 'https://engage-api.kenticocloud.com/v1/visitor/e3e9e191a12b9257/VisitorActions?type=1&daysAgo=5' \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json'
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;

PersonalizationClient client = new PersonalizationClient("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14");

string uid = this.Request.GetCurrentPersonalizationUid();
ActionDetails details = new ActionDetails();
details.DaysAgo = 5;

ActivityResponse visitedRecently = await personalizationClient.GetVisitorActionsAsync(uid, ActionTypeEnum.PageVisit, details);
A binary file was returned

You couldn't be authenticated

{
  "activity": true,
  "lastOccurrence": "2016-10-20T15:01:42+00:00"
}
{
  "activity": false
}

Path Params

uid
string
required

The ID of a user. Example: e3e9e191a12b9257.

Query Params

type
string
required

The type of the action performed by the user. The type parameter can have the following values: 0 (session), 1 (page visit), 2 (form submit), 3 (custom action). Example: 0.

daysAgo
int32

The range of days within which the user performed an action. For example, to check whether a contact performed an action within the last two weeks, use 14.

pageUrl
string

The URL of the page on which the user performed an action. The URL must be relative to the website root. For example, if you need to find out whether a contact performed an action on the home page of your website, use / instead of the full address.

customActionName
string

Defines a custom action. See Tracking custom actions.

 

Default values

If no optional query parameters (i.e., daysAgo, pageUrl, or customActionName) are specified, the Personalization API checks whether the action specified in the type query parameter occurred at any time and on any page on your website.

Returns

An Activity confirmation object.

Suggest Edits

Segments object

Object model description of the segments object.

 

When retrieving a list of contact's segments, the Personalization API returns a segments object with the following attributes:

Attribute
Description
Type

segments

A list of segments the visitor is a member of

a collection of segment objects

Segment object

Attribute
Description
Type

name

Name of the segment

string

Example segments object

{
  "segments": [
    {
      "name": "Regular visitors"
    },
    {
      "name": "Potential job candidates"
    }
  ]
}
Suggest Edits

View visitor's segments

Retrieve the names of segments that the specified visitor belongs to.

 
gethttps://engage-api.kenticocloud.com/v1//visitor/uid/segments
curl --request GET \
  --url https://engage-api.kenticocloud.com/v1/visitor/e3e9e191a12b9257/segments \
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json'
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;

PersonalizationClient client = new PersonalizationClient("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14");

string uid = this.Request.GetCurrentPersonalizationUid();

SegmentsResponse response = await client.GetVisitorSegmentsAsync(uid);
Segment[] segments = response.Segments;
A binary file was returned

You couldn't be authenticated

{
  "segments": [
    {
      "name": "Regular visitors"
    },
    {
      "name": "Potential job candidates"
    }
  ]
}
{
  "segments": []
}

Path Params

uid
string
required

The ID of a user. Example: e3e9e191a12b9257.

 

Returns

A Segments object containing the names of all segments the visitor belongs to. If the specified visitor is not a member of any segments, an empty Segments object is returned.

Suggest Edits

Visitors object

Object model description of the visitors object.

 

When retrieving a list of segment's vistitors, the Personalization API returns a visitors object with the following attributes:

Attribute
Description
Type

visitors

A list of visitors that are part of the segment.

a collection of Visitor object objects

Visitor object

Attribute
Description
Type

uid

User ID of the visitor.

string

Example visitors object

{
  "visitors": [
    {
      "uid": "1111136b4af00000"
    },
    {
      "uid": "1236136b4af00000"
    }
  ]
}
Suggest Edits

View segment's visitors

Retrieve all members of a specified segment.

 
gethttps://engage-api.kenticocloud.com/v1//segment/segment_name/visitors
curl --request GET \
  --url https://engage-api.kenticocloud.com/v1/segment/Potential job candidates/visitors\
  --header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1c3JfMHZRT0ZLWGtPTnpjclRtQk1RVGlqQiIsInBpZCI6IjU2OTAzMGM3LTUyYTUtNDRmNS1hMjQzLWM1Mjg1YjNlYjI0ZSIsImp0aSI6InhVMDZqRUlrbFRpU2k2RS0iLCJhdWQiOiJlbmdhZ2UtYXBpLmtlbnRpY29jbG91ZC5jb20ifQ.WuvDloUjl3raePT-2kjnc_vZKDWVMK-jRcVf2oUyJ14' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "visitors": [
    {
      "uid": "1111136b4af00000"
    },
    {
      "uid": "1236136b4af00000"
    }
  ]
}
{
  "visitors": []
}

Path Params

Project ID
string
required

The ID of your project. Example: 9d2de312-9583-4860-84c2-320f1b16c846

Segment name
string
required

Name of the segment. Example: Potential job candidates. Use the name as you see it in the user interface (including spaces).

 

Returns

A Visitors object object containing members of the segment. If the specified segment does not exist, and empty Visitors object is returned.

Paging

If the segment contains less than 1000 visitors, their user IDs are all returned together in a single response.
If the segment contains more than 1000 visitors, a simple paging mechanism is used:

  • The first response contains the first 1000 visitors and a link header containing the URL of the next page of results.
  • The last page (response) does not contain the link header.
https://engage-api.kenticocloud.com/v1/segment/Potential job candidates/visitors?token=1006>; rel="next"

Note: A response can contain slightly more than 1000 visitors, depending on the number of merged contacts.

Suggest Edits

Migration API

 

The Kentico Cloud Migration API is read-only. You can retrieve content but not add or modify it.

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. Note that if you have already activated the Delivery API for your project, we recommend you use it 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 ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgInR5cCI6ICJKV1QiDQp9.ew0KICAidWlkIjogInVzcl8wdlByM0N4ZzlpbjVDQ3YyRE1qaXdUIiwNCiAgImVtYWlsIjogImphbmNlcm1hbmtAZ21haWwuY29tIiwNCiAgImdpdmVuX25hbWUiOiAiQVBJIiwNCiAgImZhbWlseV9uYW1lIjogIkV4YW1wbGVzIiwNCiAgInZlciI6ICIxLjAuMCIsDQogICJqdGkiOiAiVmkzQXB0b285aGFiTzBUMiIsDQogICJhdWQiOiAiYXBpLWRyYWZ0LmtlbnRpY29jbG91ZC5jb20iDQp9.Gs-0zP_xu_oXQ5rM86yyNCUJW8tmt2FwBcyWjZmZhcA' \
  --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/fdb012c4-c012-407f-9116-1c78e670ec84/items' \
  --header 'authorization: Bearer ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgInR5cCI6ICJKV1QiDQp9.ew0KICAidWlkIjogInVzcl8wdlByM0N4ZzlpbjVDQ3YyRE1qaXdUIiwNCiAgImVtYWlsIjogImphbmNlcm1hbmtAZ21haWwuY29tIiwNCiAgImdpdmVuX25hbWUiOiAiQVBJIiwNCiAgImZhbWlseV9uYW1lIjogIkV4YW1wbGVzIiwNCiAgInZlciI6ICIxLjAuMCIsDQogICJqdGkiOiAiVmkzQXB0b285aGFiTzBUMiIsDQogICJhdWQiOiAiYXBpLWRyYWZ0LmtlbnRpY29jbG91ZC5jb20iDQp9.Gs-0zP_xu_oXQ5rM86yyNCUJW8tmt2FwBcyWjZmZhcA' \
  --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: 38af179c-40ba-42e7-a5ca-33b8cdcc0d45.

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/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/types' \
  --header 'authorization: Bearer ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgInR5cCI6ICJKV1QiDQp9.ew0KICAidWlkIjogInVzcl8wdlByM0N4ZzlpbjVDQ3YyRE1qaXdUIiwNCiAgImVtYWlsIjogImphbmNlcm1hbmtAZ21haWwuY29tIiwNCiAgImdpdmVuX25hbWUiOiAiQVBJIiwNCiAgImZhbWlseV9uYW1lIjogIkV4YW1wbGVzIiwNCiAgInZlciI6ICIxLjAuMCIsDQogICJqdGkiOiAiVmkzQXB0b285aGFiTzBUMiIsDQogICJhdWQiOiAiYXBpLWRyYWZ0LmtlbnRpY29jbG91ZC5jb20iDQp9.Gs-0zP_xu_oXQ5rM86yyNCUJW8tmt2FwBcyWjZmZhcA' \
  --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: 38af179c-40ba-42e7-a5ca-33b8cdcc0d45.

 

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/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/items/baccdc8b-7dd1-40ea-98bb-6a992b0558df' \
  --header 'authorization: Bearer ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgInR5cCI6ICJKV1QiDQp9.ew0KICAidWlkIjogInVzcl8wdlByM0N4ZzlpbjVDQ3YyRE1qaXdUIiwNCiAgImVtYWlsIjogImphbmNlcm1hbmtAZ21haWwuY29tIiwNCiAgImdpdmVuX25hbWUiOiAiQVBJIiwNCiAgImZhbWlseV9uYW1lIjogIkV4YW1wbGVzIiwNCiAgInZlciI6ICIxLjAuMCIsDQogICJqdGkiOiAiVmkzQXB0b285aGFiTzBUMiIsDQogICJhdWQiOiAiYXBpLWRyYWZ0LmtlbnRpY29jbG91ZC5jb20iDQp9.Gs-0zP_xu_oXQ5rM86yyNCUJW8tmt2FwBcyWjZmZhcA' \
  --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: 38af179c-40ba-42e7-a5ca-33b8cdcc0d45.

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/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/workflow' \
  --header 'authorization: Bearer ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgInR5cCI6ICJKV1QiDQp9.ew0KICAidWlkIjogInVzcl8wdlByM0N4ZzlpbjVDQ3YyRE1qaXdUIiwNCiAgImVtYWlsIjogImphbmNlcm1hbmtAZ21haWwuY29tIiwNCiAgImdpdmVuX25hbWUiOiAiQVBJIiwNCiAgImZhbWlseV9uYW1lIjogIkV4YW1wbGVzIiwNCiAgInZlciI6ICIxLjAuMCIsDQogICJqdGkiOiAiVmkzQXB0b285aGFiTzBUMiIsDQogICJhdWQiOiAiYXBpLWRyYWZ0LmtlbnRpY29jbG91ZC5jb20iDQp9.Gs-0zP_xu_oXQ5rM86yyNCUJW8tmt2FwBcyWjZmZhcA' \
  --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: 38af179c-40ba-42e7-a5ca-33b8cdcc0d45.

 

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/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/sitemap' \
  --header 'authorization: Bearer ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgInR5cCI6ICJKV1QiDQp9.ew0KICAidWlkIjogInVzcl8wdlByM0N4ZzlpbjVDQ3YyRE1qaXdUIiwNCiAgImVtYWlsIjogImphbmNlcm1hbmtAZ21haWwuY29tIiwNCiAgImdpdmVuX25hbWUiOiAiQVBJIiwNCiAgImZhbWlseV9uYW1lIjogIkV4YW1wbGVzIiwNCiAgInZlciI6ICIxLjAuMCIsDQogICJqdGkiOiAiVmkzQXB0b285aGFiTzBUMiIsDQogICJhdWQiOiAiYXBpLWRyYWZ0LmtlbnRpY29jbG91ZC5jb20iDQp9.Gs-0zP_xu_oXQ5rM86yyNCUJW8tmt2FwBcyWjZmZhcA' \
  --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: 38af179c-40ba-42e7-a5ca-33b8cdcc0d45.

 

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/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/taxonomy' \
  --header 'authorization: Bearer ew0KICAiYWxnIjogIkhTMjU2IiwNCiAgInR5cCI6ICJKV1QiDQp9.ew0KICAidWlkIjogInVzcl8wdlByM0N4ZzlpbjVDQ3YyRE1qaXdUIiwNCiAgImVtYWlsIjogImphbmNlcm1hbmtAZ21haWwuY29tIiwNCiAgImdpdmVuX25hbWUiOiAiQVBJIiwNCiAgImZhbWlseV9uYW1lIjogIkV4YW1wbGVzIiwNCiAgInZlciI6ICIxLjAuMCIsDQogICJqdGkiOiAiVmkzQXB0b285aGFiTzBUMiIsDQogICJhdWQiOiAiYXBpLWRyYWZ0LmtlbnRpY29jbG91ZC5jb20iDQp9.Gs-0zP_xu_oXQ5rM86yyNCUJW8tmt2FwBcyWjZmZhcA' \
  --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: 38af179c-40ba-42e7-a5ca-33b8cdcc0d45.

 

Returns

A list of taxonomy groups for the specified project with the taxonomy items each group contains.

Suggest Edits

Content Management API (BETA)

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

 

The Content Management API (currently in BETA) 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 your content items. When retrieving and updating content, you always work with the latest versions of content – the same as you would see in the Kentico Cloud user interface. Requests to the API are rate limited and uncached.

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

All requests to the API must be made securely with HTTP over TLS 1.2 and authenticated with a valid API key.

The Content Management 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 30 days. The reason for the expiration is that the Content Management API is currently not designed for continuous content migration or modification, but rather a onetime processing of data into the system, i.e., your Kentico Cloud project.

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

If you regenerate an API key before its expiration date, the system will revoke the previous API key and respond with a 403 Forbidden HTTP status code.

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.

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.

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

On the last page of results, the pagination object is omitted from the response.

Attribute Description Type Notes
continuation_token Identifier of the next page of results string
next_page URL to the next page of results string

Example: Content items listing

{
    "items": [
        # array of Content item objects
    ],
    "pagination": {
        "continuationToken": "MjA=",
        "next_page": "https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items?continuationToken=MjA%3d"
    }
}

Example: Assets listing

{
    "assets": [
        # array of Asset objects
    ],
    "pagination": {
        "continuationToken": "MjA=",
        "next_page": "https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets?continuationToken=MjA%3d"
    }
}
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 content item 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:

To retrieve content item 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

Content item variant model

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

 

The content item variant object represents a language variant of a content item. For example, when your project contains 2 active project 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 not found error.

Every content item variant is always tied to a specific content item and project language. This means you can mix and match the codenames, internal and external IDs of content items and codenames or IDs of languages when referencing the content item variants, depending on your preference.

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

These endpoints accept GET, PUT, and DELETE requests, allowing you to retrieve, upsert, and delete content item variants.

Content item variant object

Attribute Description Type Notes
item Reference to the content item Reference
elements List of content elements list of 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: Content item 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 content item 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, 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

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

Modular content

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

When retrieving Modular content elements, the Content Management API will always reference content items with their internal IDs. When updating Modular content 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 content item variants in automatic mode, the system automatically generates the element's value based on the content item name.

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 to the content item name.

"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 modules <object ...></object
Line breaks <br>

Nesting of HTML elements in Rich text

Assets, content modules, 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, data-asset-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.

<figure data-asset-id="512047f1-2f7f-45fd-9e90-e71b8feae017">
    <img src="#" data-asset-id="512047f1-2f7f-45fd-9e90-e71b8feae017">
</figure>

Rich text – Content modules

Inline content modules in Rich text elements are defined by the block element <object>. The element requires the attributes type, data-type, and data-item-id.

<object type="application/kenticocloud" data-type="item" data-item-id="f4b3fc05-e988-4dae-9ac1-a94aba566474"></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, data-asset-external-id.

<a data-asset-id="0b590263-3fe5-4773-afae-5a3f6e511e66">Hario Mini Mill</a>

Link to a content item

Requires one of the following attributes: data-item-id, data-item-external-id.

<a data-item-id="f4b3fc05-e988-4dae-9ac1-a94aba566474">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. Similarly to the internal ID and codename 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:

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

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 to these endpoints:

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/projects/project_id/items
curl --request POST \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
    "name": "Roasting coffee",
    "type": {
        "codename": "article"
    },
    "sitemap_locations": [
        {
            "codename": "articles"
        },
        {
            "codename": "coffee"
        }
    ],
    "external_id": "59713"
}'
A binary file was returned

You couldn't be authenticated

{
    "id": "b1792dae-b5ea-41ed-b574-0d0c7976794a",
    "name": "Roasting coffee",
    "codename": "roasting_coffee",
    "type": {
        "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
    },
    "sitemap_locations": [
        {
            "id": "45a123f3-1c55-c697-7dae-78369c8f1e2c"
        },
        {
            "id": "c6e04208-d6dd-1e25-f7ac-526daf042fb6"
        }
    ],
    "external_id": "59713",
    "last_modified": "2017-09-29T12:11:50.7371038Z"
}
{
    "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

List content items

Retrieve a dynamically paginated list of content items.

 
gethttps://manage.kenticocloud.com/projects/project_id/items
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'
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"
        },
        {
            "id": "b96829e8-c00d-447f-8da8-cf4982f704fd",
            "name": "Hario Skerton Hand Grinder",
            "codename": "hario_skerton_hand_grinder",
            "type": {
                "id": "da4f1cb1-8a55-43e5-9fcc-67ad331c8888"
            },
            "sitemap_locations": [
                {
                    "id": "8fdb2025-e240-1a17-df13-b5914a681730"
                }
            ],
            "last_modified": "2016-09-01T08:41:46.1405536Z"
        },
        {
            "id": "92e7260d-d65a-45f1-8a1e-aad8162f209c",
            "name": "Madrid",
            "codename": "madrid",
            "type": {
                "id": "fe41ae5a-5fe2-420a-8560-f7d6d3533dc2"
            },
            "sitemap_locations": [
                {
                    "id": "a60fe91c-88ea-6990-fe3b-cf8f8504cd33"
                },
                {
                    "id": "ef86a740-9e4c-0b33-4275-ae78558e71a7"
                }
            ],
            "last_modified": "2016-09-01T08:36:18.0623079Z"
        },
        {
            "id": "33389c83-dcfe-48f9-b0ee-f94aeabd2b08",
            "name": "Brisbane",
            "codename": "brisbane",
            "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:34:04.9408275Z"
        },
        {
            "id": "18689ab0-e5ff-4ca5-bd13-ae3b5997c2d9",
            "name": "How we source our coffees",
            "codename": "how_we_source_our_coffees",
            "type": {
                "id": "b99ec220-0f2b-4658-a080-ff0afe92f6d1"
            },
            "sitemap_locations": [
                {
                    "id": "398551ec-3f19-b177-2661-69bed4f35e20"
                }
            ],
            "last_modified": "2016-10-20T12:47:13.65023Z"
        },
      # a few more content items
    ],
    "pagination": {
        "continuationToken": "MjA=",
        "next_page": "https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items?continuationToken=MjA%3d"
    }
}
{
    "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: MjA=.

 

Returns

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

Suggest Edits

Content item by ID

Endpoints using internal IDs to specify Content item objects.

 

The endpoints listed below use internal IDs to specify content items.

If you instead want to specify content items by their codenames, see Content item by codename.

Suggest Edits

Update a content item

Update an existing content item specified by its internal ID.

 
puthttps://manage.kenticocloud.com/projects/project_id/items/content_item_id
curl --request PUT \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
    "name": "Hario Skeleton Hand Grinder",
    "sitemap_locations": []
}'
A binary file was returned

You couldn't be authenticated

{
    "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_id
string
required

The ID of a specific content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

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

View a content item

Retrieve metadata information about a content item specified by its internal ID.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/content_item_id
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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"
        }
    ],
    "last_modified": "2017-04-04T13:45:30.7692802Z"
}
{
    "request_id": "00000000-0000-0000-8918-0080000000cd",
    "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_id
string
required

The ID of a specific content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

 

Returns

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

Suggest Edits

Delete a content item

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

If you only want to delete a specific content item variant, see how to delete a variant specified by language ID or language codename.

 
deletehttps://manage.kenticocloud.com/projects/project_id/items/content_item_id
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_id
string
required

The ID of a specific content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

 

Returns

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

Suggest Edits

List content item variants

Retrieve a list of language variants of a content item specified by its internal ID.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/content_item_id/variants
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_id
string
required

The codename of the content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

 

Returns

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

Suggest Edits

Upsert a variant by language ID

Add content to a variant in an active project language, or update an existing content item variant. Both the content item and project language are specified by their internal IDs.

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

 
puthttps://manage.kenticocloud.com/projects/project_id/items/content_item_id/variants/language_id
curl --request PUT \
  https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
  --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"
  }
}'
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-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_id
string
required

The ID of an existing content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

language_id
string
required

The ID of a project language. Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8.

Body Params

elements
array of mixed types
required

A list of content elements to be updated in the content item variant. Each content element is represented as a key-value pair. The value of the individual content elements can be a string, number, or a Reference object, depending on the type of the element. If you don't provide any value for the elements body attribute, the content item 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 the updated Content item variant object.

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

Upsert a variant by language codename

Add content to a variant in an active project language, or update an existing content item variant. The content item is specified by its internal ID and the project language is specified by its codename.

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

 
puthttps://manage.kenticocloud.com/projects/project_id/items/content_item_id/variants/codename/language_codename
curl --request PUT \
  https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/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"
  }
}'
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-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_id
string
required

The ID of an existing content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

language_codename
string
required

The codename of a project language. Note that the value is case sensitive. Example: en-US.

Body Params

elements
array of mixed types
required

A list of content elements to be updated in the content item variant. Each content element is represented as a key-value pair. The value of the individual content elements can be a string, number, or a Reference object, depending on the type of the element. If you don't provide any value for the elements body attribute, the content item 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 the updated Content item variant object.

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

View a variant by language ID

Retrieve content of a language variant of a content item. Both the content item and the project language are specified by their internal IDs.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/content_item_id/variants/language_id
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_id
string
required

The ID of the content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

language_id
string
required

The ID of the project language. Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8.

 

Returns

A single Content item 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 content item variant does not exist in the specified language.
Suggest Edits

View a variant by language codename

Retrieve content of a variant of a content item. The content item is specified by its internal ID and the project language is specified by its codename.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/content_item_id/variants/codename/language_codename
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/codename/es-ES \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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: 3c03304c-7470-40fb-9870-fb6ac2df087d.

content_item_id
string
required

The ID of the content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

language_codename
string
required

The codename of the project language. Example: es-ES.

 

Returns

A single Content item 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 content item variant does not exist in the specified language.
Suggest Edits

Delete a variant by language ID

Delete a specific content item variant. Both the content item and the project language are specified by their internal IDs. 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/projects/project_id/items/content_item_id/variants/language_id
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_id
string
required

The ID of the content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

language_id
string
required

The ID of the project language. Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8.

 

Returns

If the request was successful, the specified content item 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 content item variant does not exist in the specified language.
Suggest Edits

Delete a variant by language codename

Delete a specific content item variant. The content item is specified by its internal ID and the project language is specified by its 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/projects/project_id/items/content_item_id/variants/codename/language_codename
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/f4b3fc05-e988-4dae-9ac1-a94aba566474/variants/codename/en-US \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_id
string
required

The codename of the content item. Example: f4b3fc05-e988-4dae-9ac1-a94aba566474.

language_codename
string
required

The codename of the project language. Example: en-US.

 

Returns

If the request was successful, the specified content item 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 content item variant does not exist in the specified language.
Suggest Edits

Content item by codename

Endpoints using codenames to specify Content item objects.

 

The endpoints listed below use codenames to specify content items.

If you instead want to specify content items by their IDs, see Content item by ID.

Suggest Edits

Update a content item

Update an existing content item specified by its codename.

 
puthttps://manage.kenticocloud.com/projects/project_id/items/codename/content_item_codename
curl --request PUT \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/hario_skerton_hand_grinder \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
    "name": "Hario Skeleton Hand Grinder",
    "sitemap_locations": []
}'
A binary file was returned

You couldn't be authenticated

{
    "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_codename
string
required

The codename of an existing content item. Example: hario_skerton_hand_grinder.

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

View a content item

Retrieve metadata information about a content item specified by its codename.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/codename/content_item_codename
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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"
        }
    ],
    "last_modified": "2017-04-04T13:45:30.7692802Z"
}
{
    "request_id": "00000000-0000-0000-8918-0080000000cd",
    "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_codename
string
required

The codename of an existing content item. Example: on_roasts.

 

Returns

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

Suggest Edits

Delete a content item

Delete a content item specified by its codename. Note that deleting a content item deletes all of its language variants as well.

If you only want to delete a specific content item variant, see how to delete a variant specified by language ID or language codename.

 
deletehttps://manage.kenticocloud.com/projects/project_id/items/codename/content_item_codename
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/f4b3fc05-e988-4dae-9ac1-a94aba566474/items/codename/on_roasts \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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 'f5c9bfc4-d544-4209-bfd9-9903f441a3e3' was not found."
}

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 an existing content item. Example: on_roasts.

 

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

List content item variants

Retrieve a list of language variants of a content item specified by its codename.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/codename/content_item_codename/variants
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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-11-02T09:11:00.1067922Z"
    },
    {
        "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-62e8-0080000000ee",
    "error_code": 0,
    "message": "The requested content item 'on_roasts' was not found."
}

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 an existing content item. Example: on_roasts.

 

Returns

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

Suggest Edits

Upsert a variant by language ID

Add content to a variant in an active project language, or update an existing content item variant. The content item is specified by its codename and the project language is specified by its internal ID.

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

 
puthttps://manage.kenticocloud.com/projects/project_id/items/codename/content_item_codename/variants/language_id
curl --request PUT \
  https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
  --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"
  }
}'
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-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_codename
string
required

The codename of an existing content item. Note that the value is case sensitive. Example: on_roasts.

language_id
string
required

The ID of the project language. Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8.

Body Params

elements
array of mixed types
required

A list of content elements to be updated in the content item variant. Each content element is represented as a key-value pair. The value of the individual content elements can be a string, number, or a Reference object, depending on the type of the element. If you don't provide any value for the elements body attribute, the content item 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 the updated Content item variant object.

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

Upsert a variant by language codename

Add content to a variant in an active project language, or update an existing content item variant. Both the content item and project language are specified by their codenames.

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

 
puthttps://manage.kenticocloud.com/projects/project_id/items/codename/content_item_codename/variants/codename/language_codename
curl --request PUT \
  https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/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"
  }
}'
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-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_codename
string
required

The codename of an existing content item. Note that the value is case sensitive. Example: on_roasts.

language_codename
string
required

The codename of a project language. Note that the value is case sensitive. Example: en-US.

Body Params

elements
array of mixed types
required

A list of content elements to be updated in the content item variant. Each content element is represented as a key-value pair. The value of the individual content elements can be a string, number, or a Reference object, depending on the type of the element. If you don't provide any value for the elements body attribute, the content item 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 the updated Content item variant object.

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

View a variant by language ID

Retrieve content of a variant of a content item. The content item is specified by codename and the project language is specified its internal ID.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/codename/content_item_codename/variants/language_id
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_codename
string
required

The codename of an existing content item. Example: on_roasts.

language_id
string
required

The ID of the project language. Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8.

 

Returns

A single Content item 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 content item variant does not exist in the specified language.
Suggest Edits

View a variant by language codename

Retrieve content of a language variant of a content item. Both the content item and the language are specified by their codenames.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/codename/content_item_codename/variants/codename/language_codename
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/codename/es-ES \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_codename
string
required

The codename of an existing content item. Example: on_roasts.

language_codename
string
required

The codename of the project language. Example: es-ES.

 

Returns

A single Content item 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 content item variant does not exist in the specified language.
Suggest Edits

Delete a variant by language ID

Delete a specific content item variant. The content item is specified by codename and the project language is specified its internal ID. 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/projects/project_id/items/codename/content_item_codename/variants/language_id
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_codename
string
required

The codename of the content item. Example: on_roasts.

language_id
string
required

The codename of the project language. Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8.

 

Returns

If the request was successful, the specified content item 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 content item variant does not exist in the specified language.
Suggest Edits

Delete a variant by language codename

Delete a specific content item variant. Both the content item and the project language are specified by their codenames. 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/projects/project_id/items/codename/content_item_codename/variants/codename/language_codename
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/codename/on_roasts/variants/en-US \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_codename
string
required

The codename of the content item. Example: on_roasts.

language_codename
string
required

The codename of the project language. Example: en-US.

 

Returns

If the request was successful, the specified content item 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 content item variant does not exist in the specified language.
Suggest Edits

Content item by external ID

Endpoints using external IDs to specify Content item objects.

 

The endpoints listed below use external IDs to specify content items.

To specify content items by their internal IDs, see Content item by ID, or, alternatively, see Content item by codename to use codenames instead.

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/projects/project_id/items/external-id/content_item_external_id
curl --request PUT \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json' \
  --data '
{
    "name": "Hario Skeleton Hand Grinder",
    "type": {
       "codename": "article"
    },
    "sitemap_locations": []
}'
A binary file was returned

You couldn't be authenticated

{
    "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": [],
    "external_id": "59713",
    "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 along with the modified or 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. 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.

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

Suggest Edits

View a content item

Retrieve metadata information about a content item specified by its external ID.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/external-id/content_item_external_id
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_external_id
string
required

The external ID of an existing content item. Example: 59713.

 

Returns

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

Suggest Edits

Delete a content item

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

If you only want to delete a specific content item variant, see how to Delete a variant by language ID.

 
deletehttps://manage.kenticocloud.com/projects/project_id/items/external-id/content_item_external_id
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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 '59713' was not found."
}

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 an existing content item. Example: 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

List content item variants

Retrieve a list of language variants of a content item specified by its 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/projects/project_id/items/external-id/content_item_external_id/variants
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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-11-02T09:11:00.1067922Z"
    },
    {
        "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-62e8-0080000000ee",
    "error_code": 0,
    "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_external_id
string
required

The external ID of an existing content item. Example: 59713.

 

Returns

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

Suggest Edits

Upsert a variant by language ID

Add content to a variant in an active project language, or update an existing content item variant. The content item is specified by its external ID and the project language is specified by its internal ID.

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

 
puthttps://manage.kenticocloud.com/projects/project_id/items/external-id/content_item_external_id/variants/language_id
curl --request PUT \
  https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
  --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"
  }
}'
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-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_external_id
string
required

The external ID of an existing content item. Example: 59713.

language_id
string
required

The ID of the project language. Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8.

Body Params

elements
array of mixed types
required

A list of content elements to be updated in the content item variant. Each content element is represented as a key-value pair. The value of the individual content elements can be a string, number, or a Reference object, depending on the type of the element. If you don't provide any value for the elements body attribute, the content item 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 the updated Content item variant object.

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

Upsert a variant by language codename

Add content to a variant in an active project language, or update an existing content item variant. The content item is specified by its external ID and the project language is specified by its codename.

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

 
puthttps://manage.kenticocloud.com/projects/project_id/items/external-id/content_item_external_id/variants/codename/language_codename
curl --request PUT \
  https://manage.kenticocloud.com/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"
  }
}'
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-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_external_id
string
required

The external ID of an existing content item. Example: 59713.

language_codename
string
required

The codename of a project language. Note that the value is case sensitive. Example: en-US.

Body Params

elements
array of mixed types
required

A list of content elements to be updated in the content item variant. Each content element is represented as a key-value pair. The value of the individual content elements can be a string, number, or a Reference object, depending on the type of the element. If you don't provide any value for the elements body attribute, the content item 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 the updated Content item variant object.

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

View a variant by language ID

Retrieve content of a variant of a content item. The content item is specified by its external ID and the project language is specified by its internal ID.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/external-id/content_item_external_id/variants/language_id
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_external_id
string
required

The external ID of an existing content item. Example: 59713.

language_id
string
required

The ID of the project language. Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8.

 

Returns

A single Content item 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 content item variant does not exist in the specified language.
Suggest Edits

View a variant by language codename

Retrieve content of a variant of a content item. The content item is specified by its external ID and the project language is specified by its codename.

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

 
gethttps://manage.kenticocloud.com/projects/project_id/items/external-id/content_item_external_id/variants/codename/language_codename
curl --request GET \
  --url https://manage.kenticocloud.com/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'
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: 3c03304c-7470-40fb-9870-fb6ac2df087d.

content_item_external_id
string
required

The external ID of the content item. Example: 59713.

language_codename
string
required

The codename of the project language. Example: es-ES.

 

Returns

A single Content item 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 content item variant does not exist in the specified language.
Suggest Edits

Delete a variant by language ID

Delete a specific content item variant. The content item is specified by its external ID and the project language is specified by its internal ID. 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/projects/project_id/items/external-id/content_item_external_id/variants/language_id
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/d1f95fde-af02-b3b5-bd9e-f232311ccab8 \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_external_id
string
required

The external ID of the content item. Example: 59713.

language_id
string
required

The codename of the project language. Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8.

 

Returns

If the request was successful, the specified content item 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 content item variant does not exist in the specified language.
Suggest Edits

Delete a variant by language codename

Delete a specific content item variant. The content item is specified by its external ID and the project language is specified by its 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/projects/project_id/items/external-id/content_item_external_id/variants/codename/language_codename
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/external-id/59713/variants/codename/en-US \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_external_id
string
required

The external ID of the content item. Example: 59713.

language_codename
string
required

The codename of the project language. Example: en-US.

 

Returns

If the request was successful, the specified content item 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 content item 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. 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.
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",
    "size": 125770,
    "type": "image/jpeg",
    "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

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/projects/project_id/files/file_name
curl --request POST \
  --url https://manage.kenticocloud.com/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'
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/projects/project_id/assets
curl --request POST \
  --url https://manage.kenticocloud.com/projects/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"
    },
    "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é"
        }
    ]
}'
A binary file was returned

You couldn't be authenticated

{
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "file_name": "which-brewing-fits-you-1080px.jpg",
    "size": 125770,
    "type": "image/jpeg",
    "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.

descriptions
array of objects
required

An array of asset descriptions.

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.

 

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 external_id attribute contains the same value as an already existing asset within the specified project.
  • The request is malformed.
Suggest Edits

List assets

Retrieve a dynamically paginated list of assets.

 
gethttps://manage.kenticocloud.com/projects/project_id/assets
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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",
      "size": 125770,
      "type": "image/jpeg",
      "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",
      "size": 114844,
      "type": "image/jpeg",
      "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",
      "size": 275350,
      "type": "image/jpeg",
      "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": {
    "continuationToken": null,
    "next_page": null
  }
}
{
    "assets": [],
    "pagination": {
        "continuationToken": null,
        "next_page": null
    }
}

Path Params

project_id
string
required

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

 

Returns

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

Suggest Edits

Asset by ID

Endpoints using internal IDs to specify Asset objects.

 

The endpoints listed below specify assets by their internal IDs.

If you instead want to specify assets by their external IDs, see Asset by external ID.

Suggest Edits

Update an asset by ID

Modify properties of an asset specified by its internal ID.

NOTE: This endpoint only allows updating of asset descriptions.

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

You couldn't be authenticated

{
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "file_name": "which-brewing-fits-you-1080px.jpg",
    "size": 125770,
    "type": "image/jpeg",
    "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-6b0a-0080000000dd",
    "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

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 contains invalid asset description objects.
  • The request is malformed.
Suggest Edits

View an asset by ID

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

 
gethttps://manage.kenticocloud.com/projects/project_id/assets/asset_id
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/fcbb12e6-66a3-4672-85d9-d502d16b8d9c \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "file_name": "which-brewing-fits-you-1080px.jpg",
    "size": 125770,
    "type": "image/jpeg",
    "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_id
string
required

The ID of a specific asset. Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c.

 

Returns

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

Suggest Edits

Delete an asset by ID

Removes an unused asset specified by its internal ID.

 
deletehttps://manage.kenticocloud.com/projects/project_id/assets/asset_id
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/fcbb12e6-66a3-4672-85d9-d502d16b8d9c \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
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_id
string
required

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

 

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

Asset by external ID

Endpoints using external IDs to specify Asset objects.

 

The endpoints listed below specify assets by their external IDs.

If you instead want to specify assets by their internal IDs, see Asset by ID.

Suggest Edits

Upsert an asset by external ID

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.

 
puthttps://manage.kenticocloud.com/projects/project_id/assets/external-id/asset_external_id
curl --request PUT \
  --url https://manage.kenticocloud.com/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"
  },
  "descriptions": [
    {
      "language": {
        "codename": "en-US"
      },
      "description": "Coffee Brewing Techniques"
    },
    {
      "language": {
        "codename": "es-ES"
      },
      "description": "Técnicas para hacer café"
    }
  ]
}'
A binary file was returned

You couldn't be authenticated

{
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "file_name": "which-brewing-fits-you-1080px.jpg",
    "size": 125770,
    "type": "image/jpeg",
    "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",
    "external_id": "which-brewing-fits-you"
}
{
    "request_id": "00000000-0000-0000-a914-0080000000df",
    "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 'language' not found in JSON. Path 'descriptions[0]', line 9, position 5.",
            "path": "descriptions[0]",
            "line": 9,
            "position": 5
        }
    ]
}

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

descriptions
array of objects
required

An array of asset descriptions.

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.

 

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 value of the external_id attribute does not match the external ID specified in the URL.
  • The request is malformed.
Suggest Edits

View an asset by external ID

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

 
gethttps://manage.kenticocloud.com/projects/project_id/assets/external-id/asset_external_id
curl --request GET \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/external-id/which-brewing-fits-you \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
    "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    "file_name": "which-brewing-fits-you-1080px.jpg",
    "size": 125770,
    "type": "image/jpeg",
    "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 was not found."
}

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 a specific asset. Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c.

 

Returns

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

Suggest Edits

Delete an asset by external ID

Removes an unused asset specified by its external ID.

 
deletehttps://manage.kenticocloud.com/projects/project_id/assets/external-id/asset_external_id
curl --request DELETE \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/assets/external-id/which-brewing-fits-you \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
A binary file was returned

You couldn't be authenticated

 
{
    "request_id": "00000000-0000-0000-6f12-0080000000c7",
    "error_code": 105,
    "message": "The requested asset 'which-brewing-fits-you' was not found."
}

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 specified asset. Example: 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

Tracking API (BETA)

 

The Kentico Cloud Tracking API is write-only. It allows you to track your users or visitors directly, without the use of our JavaScript tracking code. You can use it, for example, together with Personalization API to personalize content in your mobile application.

The base URL for all requests is https://engage-ket.kenticocloud.com/api/v1/track/<YOUR_PROJECT_ID>/.

At this time, requests to Tracking API do not need to be authenticated.

The API is still in BETA and may be subject to change.

Generating User ID and Session ID

All requests require a User ID and a Session ID as body parameters. Your application is responsible for generating unique IDs. They are 16-character-long strings which can contain any number or letter.

For inspiration, our JavaScript tracker generates IDs with the following code:

static generateRandomId(key = "uuid") {
   var hash = sha1(`${Alias.navigator.userAgent || ""}${Alias.navigator.platform || ""}${(new Date()).getTime()}${Math.random()}${Alias.document.domain || ""}${key}`).toString();
   return hash.slice(0, 16);
}

Creating sessions

When tracking users, it is important to always create a session first. This triggers the creation of an anonymous visitor in the system. Then you can submit custom activities and associate the collected data with an email address.

There can be many sessions associated with a single visitor or user. It's up to you to create new sessions in a way that makes sense for your use case. On the web, a session is defined as 30 minutes of continuous visitor activity. For a mobile application, it might make sense to create a new session every time the user opens the app.

Suggest Edits

Record a new session

Log a new session for a specified visitor.

 
posthttps://engage-ket.kenticocloud.com/api/v1/track/project_id/session
curl --request POST \
  --url https://engage-ket.kenticocloud.com/api/v1/track/9d2de312-9583-4860-84c2-320f1b16c846/session/ \
  --header 'content-type: application/json' \
  --data '{
  "uid":"1111136b4af00000",
  "sid":"111114cc62300000"
  }'
A binary file was returned

You couldn't be authenticated

  
{
  "error_id": "0HL8FO3DMESJM",
  "code": "VRM101",
  "message": "Invalid Format",
  "description": "Invalid format of required parameter: Uid",
  "errors": null
}

Path Params

project_id
string
required

The ID of your project. Example: 9d2de312-9583-4860-84c2-320f1b16c846.

Body Params

uid
string
required

User ID identifying a unique visitor. Example: 1111136b4af00000.

sid
string
required

Session ID identifying a session of the visitor. Example: 111114cc62300000.

 

Returns

If the request was successful, the API returns a 200 OK HTTP status code.
Otherwise, a 400 Bad request HTTP status code is returned with an appropriate error message.

Suggest Edits

Record a custom activity

Log a custom action for a specified visitor.

 
posthttps://engage-ket.kenticocloud.com/api/v1/track/project_id/activity
curl --request POST \
  --url https://engage-ket.kenticocloud.com/api/v1/track/9d2de312-9583-4860-84c2-320f1b16c846/activity/ \
  --header 'content-type: application/json' \
  --data '{
  "uid":"1111136b4af00000",
  "sid":"111114cc62300000",
  "name": "clicked-social-media-icon"
  }'
A binary file was returned

You couldn't be authenticated

 
{
  "error_id": "0HL8FO3DMESJQ",
  "code": "VRM100",
  "message": "Missing or empty",
  "description": "Required parameter is missing or empty: Name",
  "errors": null
}

Path Params

project_id
string
required

The ID of your project. Example: 9d2de312-9583-4860-84c2-320f1b16c846.

Body Params

uid
string
required

User ID identifying a unique visitor. Example: 1111136b4af00000.

sid
string
required

Session ID identifying a session of the visitor. Example: 111114cc62300000.

name
string
required

Name of the custom activity. Example: clicked-social-media-icon.

 

Returns

If the request was successful, the API returns a 200 OK HTTP status code.
Otherwise, a 400 Bad request HTTP status code is returned with an appropriate error message.

Suggest Edits

Submit a visitor's email address

Create a new contact profile.

 
posthttps://engage-ket.kenticocloud.com/api/v1/track/project_id/contact
curl --request POST \
  --url https://engage-ket.kenticocloud.com/api/v1/track/9d2de312-9583-4860-84c2-320f1b16c846/contact/ \
  --header 'content-type: application/json' \
  --data '{
  "uid":"1111136b4af00000",
  "sid":"111114cc62300000",
  "email":"john.snow@wall.north"
  }'
A binary file was returned

You couldn't be authenticated

 
{
  "error_id": "0HL8FO3DMESJT",
  "code": "VRM101",
  "message": "Invalid Format",
  "description": "Invalid format of required parameter: Sid",
  "errors": null
}

Path Params

project_id
string
required

The ID of your project. Example: 9d2de312-9583-4860-84c2-320f1b16c846.

Body Params

uid
string
required

User ID identifying a unique visitor. Example: 1111136b4af00000.

sid
string
required

Session ID identifying a session of the visitor. Example: 111114cc62300000.

email
string
required

Email of the visitor. Example: john.snow@wall.north.

 

Record a session first

Always create a session first and then submit the visitor's email.

Submitting an email address assumes that at least one session with the given User ID has already been recorded. If you are sending the two requests immediately after each other, it's best to practice to wait for a 200 OK response to the first request (recording a session) before sending the second one (submitting an email).

Returns

If the request was successful, the API returns a 200 OK HTTP status code. All sessions and custom activities previously logged with the provided User ID are now associated with the provided email address. The anonymous user becomes a contact and their profile is displayed in your Kentico Cloud project.

Otherwise, a 400 Bad request HTTP status code is returned with an appropriate error message.