Suggest Edits

Introduction

 

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

API overview

API name API resource Use case
Delivery API https://deliver.kenticocloud.com/<YOUR_PROJECT_ID>/
https://preview-deliver.kenticocloud.com/<YOUR_PROJECT_ID>/
Get content from Kentico Cloud to your web applications and mobile applications.
Content Management API https://manage.kenticocloud.com/projects/<YOUR_PROJECT_ID> Manage content items in Kentico Cloud projects, or import your existing content from a different system.
Personalization API https://engage-api.kenticocloud.com/v3/<resource>/<YOUR_PROJECT_ID> Optimize visitors' experience when visiting your website.
Tracking API https://engage-ket.kenticocloud.com/v3/track/<YOUR_PROJECT_ID>/ Track your visitors or users from anywhere through a REST API.
Migration API
The support ends December 31, 2018.
https://api.kenticocloud.com/draft/ Migrate content and content models from Kentico Cloud to a platform of your choice.
Personal Data API https://personal-data-api.kenticocloud.com/ View and delete personal data of your tracked visitors.

Trying out the endpoints

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

Run in Postman

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

Try any of the endpoints

Try any of the endpoints

Suggest Edits

Authentication

How and when to authenticate your requests.

 

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

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

Which APIs need authentication?

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

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

Authorization: Bearer <YOUR_API_KEY>

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

Suggest Edits

Error responses

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

 

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

HTTP error code summary

Status code Description
400
Bad Request
The request was not understood. Check your request for a missing required parameter or an invalid query parameter value.
401
Unauthorized
The provided API key is invalid or missing. See Authentication.
403
Forbidden
The provided API key is invalid for the requested project.
404
Not Found
The requested resource doesn't exist. Try checking the resource name for typos.
405
Method Not Allowed
The requested HTTP method is not supported for the specified resource. Try performing a GET request.
500
Internal Server Error
Something went wrong on our side. Try the request again in a few minutes, or contact us.

Resolving errors

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

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

Example: Mistyped codename of a content item

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

Example: Invalid value of a query parameter

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

Delivery API

 

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

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

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

API requests limits

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

Production vs. Preview

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

Retrieve published content from your project using the production URL:
https://deliver.kenticocloud.com/<YOUR_PROJECT_ID>/

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

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>'
using KenticoCloud.Delivery;

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

DeliveryClient client = new DeliveryClient(deliveryOptions);

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

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

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

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

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

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

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

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

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

ContentItem item = client.getItem("on_roasts").item;
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.elements.AssetsElement;
import com.kenticocloud.delivery_core.elements.DateTimeElement;
import com.kenticocloud.delivery_core.elements.TextElement;
import com.kenticocloud.delivery_core.interfaces.item.item.IContentItem;
import com.kenticocloud.delivery_core.models.item.ContentItem;
import com.kenticocloud.delivery_core.models.item.DeliveryItemResponse;
import com.kenticocloud.delivery_core.models.item.ElementMapping;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

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

public class ListContentItem{

    // Prepare strongly typed model
    public final class Article extends ContentItem {

        public static final String TYPE = "article";

        @ElementMapping("summary")
        public TextElement summary;

        @ElementMapping("title")
        public TextElement title;

        @ElementMapping("teaser_image")
        public AssetsElement teaserImage;

        @ElementMapping("post_date")
        public DateTimeElement postDate;
    }

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Register type resolver
        typeResolvers.add(new TypeResolver<>(Article.TYPE, new Function<Void, Article>() {
            @Override
            public Article apply(Void input) {
                return new Article();
            }
        }));

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers));

        // Use simple request to get data
        Article article = deliveryService.<Article>item("on_roasts")
                .get()
                .getItem();

        // Use RxJava2 to get the data
        deliveryService.<Article>item("on_roasts")
                .elementsParameter(Arrays.asList("title", "summary", "post_date", "teaser_image"))
                .depthParameter(1)
                .getObservable()
                .subscribe(new Observer<DeliveryItemResponse<Article>>() {
                    @Override
                    public void onSubscribe(Disposable d) {
                    }

                    @Override
                    public void onNext(DeliveryItemResponse<Article> response) {

                        // Get article
                        Article article = response.getItem();

                        // Print the Title of first article
                        System.out.println(article.title.getValue());
                    }

                    @Override
                    public void onError(Throwable e) {
                        // Print the error message
                        System.out.println(e.getMessage());
                    }

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

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

use KenticoCloud\Delivery\DeliveryClient;

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

$item = $client->getItem('on_roasts');

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. Note that filtering does NOT apply to content items returned within the modular_content collection (see Content items listing response).

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

Filtering by system values

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

Filtering by element values

To filter by content element values, you need to use a query parameter in the elements.<element_codename>=<value> format. For example, to retrieve only content items whose Number element named Price has a value of 16, you can use elements.price=16 as a query parameter.

Joining multiple query parameters

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

For example, query system.type=article&system.sitemap_locations[contains]=cafes will return the Article content items which are in the Cafes section of the project sitemap.

Filtering operators

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

Operator
Description
Example
Use with

=

Attribute value is the same as the specified value.

system.type=article

Simple types

[lt]

Attribute value is less than the specified value.

More in Comparing values.

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

Simple types

[lte]

Attribute value is less than or equals the specified value.

More in Comparing values.

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

Simple types

[gt]

Attribute value is greater than the specified value.

More in Comparing values.

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

Simple types

[gte]

Attribute value is greater than or equals the specified value.

More in Comparing values.

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

Simple types

[range]

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

More in Comparing values.

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

Simple types

[in]

Attribute value is in the specified list of values.

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

Simple types

[contains]

Attribute with an array of values contains the specified value.

system.sitemap_locations[contains]=cafes

Arrays

[any]

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

elements.personas[any]=barista,coffee_blogger

Arrays

[all]

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

elements.personas[all]=barista,coffee_blogger

Arrays

Arrays vs. simple types

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

Comparing values

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

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

Suggest Edits

Ordering

Sort the content in a listing response.

 

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

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

Examples

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

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

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

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

Suggest Edits

Projection

Choose specific content elements to retrieve when getting content items.

 

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

Using projection

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

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

Note: Projection does not apply to the system attributes. You cannot omit the System object from the JSON response by using any query.

Suggest Edits

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.

Note: When retrieving content items, modular content cannot be filtered.

Suggest Edits

Secure access

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

 

Premium feature

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

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

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

The scope of the API keys is per project. This means you need a separate API key for each project in Kentico Cloud. All of the users contributing to the same project share the API keys.

Suggest Edits

Revoking the API keys

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

 

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

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

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

Example: API key revocation

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

Image transformation

Transform your images in real-time using Delivery API.

 

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

Input and output formats

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

  • jpeg, png, gif, and webp

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

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

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

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

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

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

Working with the image URLs

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

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

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

Size

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

 

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

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

Image width (w)

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

Value
Units
Description
Example

Integer

Pixels

A whole number between 1 and 8192.

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

Float

Percentage

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

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

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

Image height (h)

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

Value
Units
Description
Example

Integer

Pixels

A whole number between 1 and 8192.

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

Float

Percentage

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

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

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

Device pixel ratio (dpr)

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

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

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

Value
Description
Example

dpr

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

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

Resize fit mode (fit)

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

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

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

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

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

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

Fit mode
Description
Aspect ratio
Example

clip

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

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

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

scale

Scales the image to fit the constraining dimensions exactly.

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

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

crop

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

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

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

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

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

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

Source rectangle region (rect)

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

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

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

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

Values
Units
Description
Example

Integer

Pixels

A whole number between 1 and 8192.

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

Float

Percentage

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

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

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

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

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

Suggest Edits

Focal point crop

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

 

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

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

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

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

Focal point crop consists of the following parameters:

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

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

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

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

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

Suggest Edits

Format

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

 

Format parameter

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

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

Value
Description
Quality parameter

gif

Graphics Interchange Format

No

png

Portable Network Graphics

No

png8

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

No

jpg

JPEG

Yes

pjpg

Progressive JPEG

Yes

webp

WebP

Yes

Quality parameter (jpg, pjpg, webp)

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

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

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

Lossless parameter (webp)

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

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

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

Automatic format selection (webp)

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

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

Suggest Edits

List content items

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

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

public class ListContentItems{

    // Prepare strongly typed model
    public final class Article extends ContentItem {

        public static final String TYPE = "article";

        @ElementMapping("summary")
        public TextElement summary;

        @ElementMapping("title")
        public TextElement title;

        @ElementMapping("teaser_image")
        public AssetsElement teaserImage;

        @ElementMapping("post_date")
        public DateTimeElement postDate;
    }

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Register type resolver
        typeResolvers.add(new TypeResolver<>(Article.TYPE, new Function<Void, Article>() {
            @Override
            public Article apply(Void input) {
                return new Article();
            }
        }));

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers));

        // Use simple request to get data
        List<Article> articles = deliveryService.<Article>items()
                .equalsFilter("system.type", "article")
                .elementsParameter(Arrays.asList("title", "summary", "post_date", "teaser_image"))
                .orderParameter("elements.post_date", OrderType.Desc)
                .limitParameter(3)
                .get()
                .getItems();

        // Use RxJava2 to get the data
        deliveryService.<Article>items()
                .equalsFilter("system.type", "article")
                .elementsParameter(Arrays.asList("title", "summary", "post_date", "teaser_image"))
                .orderParameter("elements.post_date", OrderType.Desc)
                .limitParameter(3)
                .getObservable()
                .subscribe(new Observer<DeliveryItemListingResponse<Article>>() {
                    @Override
                    public void onSubscribe(Disposable d) {
                    }

                    @Override
                    public void onNext(DeliveryItemListingResponse<Article> response) {

                        // Get your mapped articles
                        List<Article> articles = response.getItems();

                        // Get first article
                        Article firstArticle = articles.get(0);

                        // Print the Title of first article
                        System.out.println(firstArticle.title.getValue());
                    }

                    @Override
                    public void onError(Throwable e) {
	                      // Print the error message
                        System.out.println(e.getMessage());
                    }

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

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

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

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

Query Params

language
string

Determines which language variant of content to return. By default, the API returns content in the default project language. If the requested content is not available in the specified language variant, the API follows the language fallbacks as configured in the Localization settings of your project. Example: en-US.

elements
string

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

order
string

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

depth
int32

Content items can 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 Notes
item Content item data collection of the system and elements attributes
system System attributes of the content item System object
elements Content type elements in the content item collection of Element objects The order of the Element objects might not match the order in the UI.
modular_content A list of content items used in Modular content and Rich text elements collection of Content item objects The Content item objects are returned in no particular order and cannot be filtered.

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 { ContentItem, DeliveryClient, Fields, TypeResolver, SortOrder } from 'kentico-cloud-delivery';

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

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

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

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

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

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

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

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

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

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

client.getItem(modelType: Article.self, itemName: "on_roasts") { (isSuccess, deliveryItem, error) in
     if isSuccess {
        if let article = deliveryItem.item {
            // Use your item here
        }
    } else {
        if let error = error {
            print(error)
        }
    }
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.elements.AssetsElement;
import com.kenticocloud.delivery_core.elements.DateTimeElement;
import com.kenticocloud.delivery_core.elements.TextElement;
import com.kenticocloud.delivery_core.interfaces.item.item.IContentItem;
import com.kenticocloud.delivery_core.models.item.ContentItem;
import com.kenticocloud.delivery_core.models.item.DeliveryItemResponse;
import com.kenticocloud.delivery_core.models.item.ElementMapping;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

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

public class ListContentItem{

    // Prepare strongly typed model
    public final class Article extends ContentItem {

        public static final String TYPE = "article";

        @ElementMapping("summary")
        public TextElement summary;

        @ElementMapping("title")
        public TextElement title;

        @ElementMapping("teaser_image")
        public AssetsElement teaserImage;

        @ElementMapping("post_date")
        public DateTimeElement postDate;
    }

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Register type resolver
        typeResolvers.add(new TypeResolver<>(Article.TYPE, new Function<Void, Article>() {
            @Override
            public Article apply(Void input) {
                return new Article();
            }
        }));

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers));

        // Use simple request to get data
        Article article = deliveryService.<Article>item("on_roasts")
                .get()
                .getItem();

        // Use RxJava2 to get the data
        deliveryService.<Article>item("on_roasts")
                .getObservable()
                .subscribe(new Observer<DeliveryItemResponse<Article>>() {
                    @Override
                    public void onSubscribe(Disposable d) {
                    }

                    @Override
                    public void onNext(DeliveryItemResponse<Article> response) {

                        // Get article
                        Article article = response.getItem();

                        // Print the Title of first article
                        System.out.println(article.title.getValue());
                    }

                    @Override
                    public void onError(Throwable e) {
                        // Print the error message
                        System.out.println(e.getMessage());
                    }

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

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

use KenticoCloud\Delivery\DeliveryClient;

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

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

You couldn't be authenticated

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

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

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

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

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

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

deliveryClient.types()
    .limitParameter(3)
    .getObservable()
    .subscribe(response => console.log(response.types));
import KenticoCloud
 
let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")
 
client.getContentTypes(limit: 3, completionHandler: { (isSuccess, contentTypesResponse, error) in
    if !isSuccess {
        fail( "Response is not successful. Error: \(String(describing: error))" )
    }
     
    if let response = contentTypesResponse {
    // use content types here
    }
})
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.models.type.ContentType;
import com.kenticocloud.delivery_core.models.type.DeliveryTypeListingResponse;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.List;

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

public class ViewContentTypes {

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers));

        // Use simple request to get data
        List<ContentType> types = deliveryService.types()
                .limitParameter(3)
                .get()
                .getTypes();

        // Use RxJava2 to get the data
        deliveryService.types()
                .limitParameter(3)
                .getObservable()
                .subscribe(new Observer<DeliveryTypeListingResponse>() {
                    @Override
                    public void onSubscribe(Disposable d) {

                    }

                    @Override
                    public void onNext(DeliveryTypeListingResponse response) {

                        // Get types from response
                        List<ContentType> types = response.getTypes();

                        // Print codename of first content type
                        System.out.println(types.get(0).getSystem().getCodename());
                    }

                    @Override
                    public void onError(Throwable e) {
	                      // Print the error message
                        System.out.println(e.getMessage());
                    }

                    @Override
                    public void onComplete() {

                    }
                });
    }
}
<?php

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

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

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

Query Params

skip
int32

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

limit
int32

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

Headers

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

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

 

Returns

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

Suggest Edits

Content type model

Object model description of a single content type object.

 

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

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

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

System object (content type)

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

Example: Content type object

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

View a content type

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

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

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

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

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

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

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

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

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

deliveryClient.type('coffee')
    .getObservable()
    .subscribe(response => console.log(response.type));
import KenticoCloud
 
let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")
 
client.getContentType(name: "coffee", completionHandler: { (isSuccess, contentType, error) in
    if !isSuccess {
        fail( "Response is not successful. Error: \(String(describing: error))" )
    }
     
    if let type = contentType {
    // use content type here
    }
})
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.models.type.ContentType;
import com.kenticocloud.delivery_core.models.type.DeliveryTypeResponse;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.List;

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

public class ViewContentType{

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers));

        // Use simple request to get data
        ContentType type = deliveryService.type("coffee")
                .get()
                .getType();

        // Use RxJava2 to get the data
        deliveryService.type("coffee")
                .getObservable()
                .subscribe(new Observer<DeliveryTypeResponse>() {
                    @Override
                    public void onSubscribe(Disposable d) {

                    }

                    @Override
                    public void onNext(DeliveryTypeResponse response) {

                        // Get type from response
                        ContentType type = response.getType();

                        // Print codename of content type
                        System.out.println(type.getSystem().getCodename());
                    }

                    @Override
                    public void onError(Throwable e) {
	                      // Print the error message
                        System.out.println(e.getMessage());
                    }

                    @Override
                    public void onComplete() {

                    }
                });
    }
}
<?php

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

use KenticoCloud\Delivery\DeliveryClient;

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

$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 images, content modules, and links to other content items. Information about these objects is stored in the images, links, and modular_content attributes.

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

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. The list is represented as an array of strings, each string being a codename of a content item.

Multiple choice

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

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

Number

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. The objects are returned in the same order as shown in the UI.

Asset object

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

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. The order of codenames in the array matches the order of the content items in the UI.

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

Taxonomy

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

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

URL slug

The value of URL slug elements is a string.

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

Content type snippet

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

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

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

View a content type element

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

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

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

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

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

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

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

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

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

deliveryClient.element('coffee', 'processing')
    .getObservable()
    .subscribe(response => console.log(response));
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.models.element.ContentTypeElement;
import com.kenticocloud.delivery_core.models.element.DeliveryContentTypeElementResponse;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.List;

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

public class ViewContentTypeElement {

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers));

        // Use simple request to get data
        ContentTypeElement element = deliveryService.contenTypeElement("coffee", "processing")
                .get()
                .getElement();

        // Use RxJava2 to get the data
        deliveryService.contenTypeElement("coffee", "processing")
                .getObservable()
                .subscribe(new Observer<DeliveryContentTypeElementResponse>() {
                    @Override
                    public void onSubscribe(Disposable d) {

                    }

                    @Override
                    public void onNext(DeliveryContentTypeElementResponse response) {

                        // Get element
                        ContentTypeElement element = response.getElement();

                        // Print name of the element
                        System.out.println(element.getName());
                    }

                    @Override
                    public void onError(Throwable e) {
	                      // Print the error message
                        System.out.println(e.getMessage());
                    }

                    @Override
                    public void onComplete() {

                    }
                });
    }
}
<?php

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

use KenticoCloud\Delivery\DeliveryClient;

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

content_type_codename
string
required

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

element_codename
string
required

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

Headers

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

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

 

Returns

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

Suggest Edits

List taxonomy groups

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

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

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

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

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

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

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

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

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

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

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

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

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

client.getTaxonomies(completionHandler: { (isSuccess, deliveryItems, error) in
   if isSuccess {
       if let taxonomies = deliveryItems?.items {
        // use your taxonomies here
       }
    } else {
         if let error = error {
             print(error)
         }
    }
})
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.models.taxonomy.DeliveryTaxonomyListingResponse;
import com.kenticocloud.delivery_core.models.taxonomy.Taxonomy;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.List;

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

public class ViewTaxonomyGroups {

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers));

        // Use simple request to get data
        List<Taxonomy> taxonomies = deliveryService.taxonomies()
                .limitParameter(3)
                .get()
                .getTaxonomies();

        // Use RxJava2 to get the data
        deliveryService.taxonomies()
                .limitParameter(3)
                .getObservable()
                .subscribe(new Observer<DeliveryTaxonomyListingResponse>() {
                    @Override
                    public void onSubscribe(Disposable d) {

                    }

                    @Override
                    public void onNext(DeliveryTaxonomyListingResponse response) {
                        // Get taxonomies
                        List<Taxonomy> taxonomies = response.getTaxonomies();

                        // Print name of first taxonomy
                        System.out.println(taxonomies.get(0).getSystem().getName());
                    }

                    @Override
                    public void onError(Throwable e) {
	                      // Print the error message
                        System.out.println(e.getMessage());
                    }

                    @Override
                    public void onComplete() {

                    }
                });
    }
}
<?php

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

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

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

Query Params

skip
int32

Number of taxonomy groups to skip. Example: 10.

limit
int32

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

Headers

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

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

 

Returns

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

Suggest Edits

Taxonomy group model

Object model description of a single taxonomy group object.

 

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

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

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

System object (taxonomy group)

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

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

Term object (taxonomy group)

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

Example: Taxonomy group object

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

Example: Taxonomy term object

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

View a taxonomy group

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

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

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

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

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

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

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

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

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

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

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

client.getTaxonomyGroup(taxonomyGroupName: "personas", completionHandler: { (isSuccess, deliveryItem, error) in
   if isSuccess {
       if let taxonomyGroup = deliveryItems.item {
        // use your taxonomy group here
       }
    } else {
         if let error = error {
             print(error)
         }
    }
})
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.models.taxonomy.DeliveryTaxonomyResponse;
import com.kenticocloud.delivery_core.models.taxonomy.Taxonomy;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.List;

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

public class ViewTaxonomyGroup {

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("e391c776-9d1e-4e1a-8a5a-1c327c2586b6", typeResolvers));

        // Use simple request to get data
        Taxonomy taxonomy = deliveryService.taxonomy("personas")
                .get()
                .getTaxonomy();

        // Use RxJava2 to get the data
        deliveryService.taxonomy("personas")
                .getObservable()
                .subscribe(new Observer<DeliveryTaxonomyResponse>() {
                    @Override
                    public void onSubscribe(Disposable d) {
                    }

                    @Override
                    public void onNext(DeliveryTaxonomyResponse response) {
                        // Get taxonomy
                        Taxonomy taxonomy = response.getTaxonomy();

                        // Print name of taxonomy
                        System.out.println(taxonomy.getSystem().getName());
                    }

                    @Override
                    public void onError(Throwable e) {
	                      // Print the error message
                        System.out.println(e.getMessage());
                    }

                    @Override
                    public void onComplete() {

                    }
                });
    }
}
<?php

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

use KenticoCloud\Delivery\DeliveryClient;

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

taxonomy_group_codename
string
required

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

Headers

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

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

 

Returns

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

Suggest Edits

Webhooks and notifications

 

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

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

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

Notification model

Each notification comes as JSON with the following attributes:

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

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

Notification message object

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

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

Notification data object

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

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

Item object

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

Taxonomy group object

Attribute Description Type
codename Codename of the modified taxonomy group string

Example webhook call on content change

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

Types and operations

 

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

Types

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

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

Operations

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

Operation Description Applies to types
archive A data model was deleted content_item, 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_type, sitemap, taxonomy

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

Suggest Edits

Notification signatures

 

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

X-KC-Signature: fRbrQ1lpBSRB9T3MckJ51HDdjQ8UuV3WnjqKqirSpW8=

Verifying webhook notifications

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

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

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

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

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

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

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

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

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

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

Content Management API

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

 

Premium feature

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

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

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

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

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

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

API requests limits

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

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

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

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

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

API key scope and validity

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

 

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

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

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

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

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

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

Example: API key revocation

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

Rate limiting

 

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

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

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

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

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

Example: Reaching the rate limit

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

Listing response

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

 

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

Content items listing response

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

Assets listing response

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

Pagination object

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

Example: Content items listing

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

Example: Assets listing

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

Content item model

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

 

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

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

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

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

Content item object

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

Example: Content item object

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

List content items

Retrieve a dynamically paginated list of content items.

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

You couldn't be authenticated

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

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

Path Params

project_id
string
required

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

Query Params

continuationToken
string

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

 

Returns

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

Suggest Edits

View a content item

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

content_item_identifier
string
required

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

 

Returns

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

Suggest Edits

Add a content item

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

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

Body Params

name
string
required

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

type
object
required

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

sitemap_locations
array of objects

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

external_id
string

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

 

Returns

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

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

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

Update a content item

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

content_item_identifier
string
required

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

Body Params

name
string
required

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

sitemap_locations
array of objects
required

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

 

Returns

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

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

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

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

Suggest Edits

Upsert a content item

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

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

string externalId = "59713";

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

content_item_external_id
string
required

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

Body Params

name
string
required

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

type
object
required

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

sitemap_locations
array of objects
required

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

 

Returns

If the request was successful, the API returns:

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

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

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

Delete a content item

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

content_item_identifier
string
required

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

 

Returns

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

Suggest Edits

Language variant model

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

 

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

Deactivated languages

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

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

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

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

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

Language variant object

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

Example: Language variant object

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

Content element model

Object model descriptions of individual elements.

 

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

Element object

The values of content elements can be strings (Text, Rich text, Date & Time, and URL slug elements), decimal numbers (Number element), and arrays of Reference objects (Multiple choice, Asset, 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 language variants in automatic mode, the system automatically generates the element's value based on the Text element of your choice.

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

"url_pattern": "on-roasts"
Suggest Edits

Rich text element

 

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

Types HTML elements Notes
Paragraphs <p>...</p>
Headings <h1>...</h1>, <h2>...</h2>, <h3>...</h3>, <h4>...</h4>
Bold text <strong>...</strong> <b> tag is not supported.
Italic text <em>...</em> <i> tag is not supported.
Lists <ol><li>...</li></ol>, <ul><li>...</li></ul>
Tables <table><tbody><tr><td>...</td></tr></tbody></table> <thead> and <tfoot> tags are not supported.
Links <a ...>...</a>
Assets <figure ...><img ...></figure>
Content 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 or data-asset-external-id. The data-asset-external-id attribute can also reference an object that was not yet imported to Kentico Cloud. For more details, see Referencing by external ID.

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

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

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

Rich text – Content modules

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

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

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

Rich text – Links

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

Links to a URL address

Requires the attribute href.

Inserting URL values

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

Examples of how inserted URLs are stored:

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

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

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

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

Link with an email address

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

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

Link to an asset

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

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

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

Link to a content item

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

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

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

Rich text – Lists

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

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

Rich text – Tables

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

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

Reference object

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

 

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

Referencing with external IDs

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

See Referencing by external ID for more details.

Reference object

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

Example: Referencing content items

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

Referencing by external ID

Reference other objects by their external IDs.

 

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

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

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

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

Referencing non-existing objects

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

  • Modular Content
  • Assets
  • Rich Text (as assets, content modules, and links)

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

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

Restricted View

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

To add the the missing objects, see:

Example: Referencing non-existing content items

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

List language variants of an item

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

content_item_identifier
string
required

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

 

Returns

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

Suggest Edits

View a language variant

Retrieve content of a language variant of a content item.

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

ContentItemVariantIdentifier variantIdentifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier);

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

A binary file was returned

You couldn't be authenticated

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

Path Params

project_id
string
required

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

content_item_identifier
string
required

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

language_identifier
string
required

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

 

Returns

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

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

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

Upsert a language variant

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

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

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


ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier);

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

content_item_identifier
string
required

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

language_identifier
string
required

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

Body Params

elements
object
required

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

 

Returns

If the request was successful, the API returns:

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

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

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

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

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

Delete a language variant

Delete a specific language variant.

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

ContentItemVariantIdentifier identifier = new ContentItemVariantIdentifier(itemIdentifier, languageIdentifier);

await client.DeleteContentItemVariantAsync(identifier);

A binary file was returned

You couldn't be authenticated

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

Path Params

project_id
string
required

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

content_item_identifier
string
required

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

language_identifier
string
required

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

 

Returns

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

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

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

Asset model

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

 

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

Creating new assets

Adding an asset is a 2-step process:

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

Asset object

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

Asset file reference object

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

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

Asset description object

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

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

Example: Asset object

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

List assets

Retrieve a dynamically paginated list of assets.

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

Query Params

continuationToken
string

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

 

Returns

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

Suggest Edits

View an asset

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

asset_identifier
string
required

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

 

Returns

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

Suggest Edits

Upload a binary file

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

file_name
string
required

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

Headers

Content-type
string
required

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

Content-length
int32
required

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

 

Returns

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

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

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

Add an asset

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

Body Params

file_reference
object
required

The reference to the binary file.

file_reference.id
string
required

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

file_reference.type
string
required

The type of the reference. Example: internal.

title
string

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

external_id
string

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

descriptions
array of objects
required

An array of asset descriptions.

 

Returns

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

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

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

Update an asset

Modify properties of an asset specified by its internal ID.

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

string title = "Coffe Brewing Techniques";

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

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

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

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

asset_id
string
required

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

Body Params

title
string

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

descriptions
array of objects
required

An array of asset descriptions.

 

Returns

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

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

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

Upsert an asset

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

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

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

string title = "Coffe Brewing Techniques";

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

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

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

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

asset_external_id
string
required

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

Body Params

file_reference
object
required

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

file_reference.id
string
required

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

file_reference.type
string
required

The type of the reference. Example: internal.

title
string

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

descriptions
array of objects
required

An array of asset descriptions.

 

Returns

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

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

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

Delete an asset

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

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

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

ContentManagementClient client = new ContentManagementClient(options);

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

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

You couldn't be authenticated

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

Path Params

project_id
string
required

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

asset_identifier
string
required

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

 

Returns

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

Suggest Edits

Project report model

Object model description of the project report model.

 

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

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

Project report model

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

Project object

The project object contains the project ID and display name.

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

Variant issue object

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

Attribute Description Type
item Information about the content item Content item metadata object
language Information about the project language Language metadata object
issues Information about issues found in specific content elements array of Content element issue objects

Variant issue – Content item metadata

Attribute Description Type
id ID of the content item string
name Display name of the content item string
codename Codename of the content item string

Variant issue – Language metadata

Attribute Description Type
id ID of the project language string
name Display name of the project language string
codename Codename of the project language string

Variant issue – Content element issue

For each issue found in a specific language variant, the issues array will contain a content element issue with metadata about the content element and an array of validation messages describing the problem.

Attribute Description Type
element Information about the content element Content element metadata object
messages Validation messages for the content element array of strings

Variant issue – Content element metadata

Attribute Description Type
id ID of the element string
name Display name of the element string
codename Codename of the element string

Example: Validity report object

{
  "project": {
    "id": "975bf280-fd91-488c-994c-2f04416e5ee3",
    "name": "Sample Project"
  },
  "variant_issues": [
    {
      "item": {
        "id": "b2fea94c-73fd-42ec-a22f-f409878de187",
        "name": "Origins of Arabica Bourbon",
        "codename": "origins_of_arabica_bourbon"
      },
      "language": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "English (United States)",
        "codename": "en-US"
      },
      "issues": [
        {
          "element": {
            "id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
            "name": "Related articles",
            "codename": "related_articles"
          },
          "messages": [
            "Element 'Related articles' contains a content module Colombia Carlos Imbachi of type Coffee that is not allowed in this context."
          ]
        }
      ]
    },
    {
      "item": {
        "id": "cf106f4e-30a4-42ef-b313-b8ea3fd3e5c5",
        "name": "Coffee Beverages Explained",
        "codename": "coffee_beverages_explained"
      },
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8",
        "name": "Spanish (Spain)",
        "codename": "es-ES"
      },
      "issues": [
        {
          "element": {
            "id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
            "name": "Related articles",
            "codename": "related_articles"
          },
          "messages": [
            "Element 'Related articles' is required but has no value",
            "Element 'Related articles' should have at least 1 content module(s) but has 0 content module(s)."
          ]
        },
        {
          "element": {
            "id": "b9dc537c-2518-e4f5-8325-ce4fce26171e",
            "name": "Meta description",
            "codename": "meta_description"
          },
          "messages": [
            "Element 'Meta description' should have at most 160 characters(s) but has 174 character(s)."
          ]
        }
      ]
    }
  ]
}
Suggest Edits

Validate project content

Checks your project's content items for issues, such as:

  • Content elements referencing non-existing objects.
  • Values of certain content elements not meeting the limitations set in content types.

We recommend that you use this endpoint after successfully importing content into your project.

 
posthttps://manage.kenticocloud.com/projects/project_id/validate
curl --request POST \
  --url https://manage.kenticocloud.com/projects/975bf280-fd91-488c-994c-2f04416e5ee3/validate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "project": {
    "id": "975bf280-fd91-488c-994c-2f04416e5ee3",
    "name": "Sample Project"
  },
  "variant_issues": [
    {
      "item": {
        "id": "b2fea94c-73fd-42ec-a22f-f409878de187",
        "name": "Origins of Arabica Bourbon",
        "codename": "origins_of_arabica_bourbon"
      },
      "language": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "English (United States)",
        "codename": "en-US"
      },
      "issues": [
        {
          "element": {
            "id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
            "name": "Related articles",
            "codename": "related_articles"
          },
          "messages": [
            "Element 'Related articles' contains a content module Colombia Carlos Imbachi of type Coffee that is not allowed in this context."
          ]
        }
      ]
    },
    {
      "item": {
        "id": "cf106f4e-30a4-42ef-b313-b8ea3fd3e5c5",
        "name": "Coffee Beverages Explained",
        "codename": "coffee_beverages_explained"
      },
      "language": {
        "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8",
        "name": "Spanish (Spain)",
        "codename": "es-ES"
      },
      "issues": [
        {
          "element": {
            "id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
            "name": "Related articles",
            "codename": "related_articles"
          },
          "messages": [
            "Element 'Related articles' is required but has no value",
            "Element 'Related articles' should have at least 1 content module(s) but has 0 content module(s)."
          ]
        },
        {
          "element": {
            "id": "b9dc537c-2518-e4f5-8325-ce4fce26171e",
            "name": "Meta description",
            "codename": "meta_description"
          },
          "messages": [
            "Element 'Meta description' should have at most 160 characters(s) but has 174 character(s)."
          ]
        }
      ]
    }
  ]
}

Path Params

project_id
string
required

The ID of your project.

 

Returns

A project report summarizing the issues found in the language variants of the specified project.

Suggest Edits

Personalization API

 

The Personalization API is a read-only REST API that retrieves data about your visitors and their segments.

The base URL for all requests is https://engage-api.kenticocloud.com/v3/.

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

curl --request GET \
  --url https://engage-api.kenticocloud.com/v3/visitor/569030c7-52a5-44f5-a243-c5285b3eb24e/e3e9e191a12b9257/segments \
  --header 'Authorization: Bearer <YOUR_PERSONALIZATION_API_KEY>' \
  --header 'content-type: application/json'

User ID

All Personalization API methods work with User ID, which identifies a specific visitor on your website. You can get this value values either by parsing the 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.

The method uses a callback with a string argument containing an ID of your visitor. Use the value when building a link to the REST interface.

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

codename

Codename of the segment

string

Example segments object

{
  "segments": [
    {
      "codename": "regular_visitors"
    },
    {
      "codename": "potential_job_candidates"
    }
  ]
}
Suggest Edits

List segments of a visitor

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

 

Header Auth

 Authentication is required for this endpoint.
gethttps://engage-api.kenticocloud.com/v3/visitor/project_id/uid/segments
curl --request GET \
  --url https://engage-api.kenticocloud.com/v3/visitor/569030c7-52a5-44f5-a243-c5285b3eb24e/e3e9e191a12b9257/segments \
  --header 'Authorization: Bearer <YOUR_PERSONALIZATION_API_KEY>' \
  --header 'content-type: application/json'
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;

var projectId = "569030c7-52a5-44f5-a243-c5285b3eb24e";
var apiKey = "<YOUR_PERSONALIZATION_API_KEY>";
PersonalizationClient client = new PersonalizationClient(apiKey, projectId);

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": [
    {
      "codename": "regular_visitors"
    },
    {
      "codename": "potential_job_candidates"
    }
  ]
}
{
  "segments": []
}

Path Params

project_id
string
required

The ID of your project. Example: 569030c7-52a5-44f5-a243-c5285b3eb24e.

uid
string
required

The ID of a visitor. Example: e3e9e191a12b9257.

 

Returns

A Segments object containing the codenames 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

List visitors of a segment

Retrieve all members of a specified segment.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://engage-api.kenticocloud.com/v3/segment/project_id/segment_codename/visitors
curl --request GET \
  --url https://engage-api.kenticocloud.com/v3/segment/569030c7-52a5-44f5-a243-c5285b3eb24e/potential_job_candidates/visitors \
  --header 'Authorization: Bearer <YOUR_PERSONALIZATION_API_KEY>' \
  --header 'content-Type: application/json'
using KenticoCloud.Personalization;
using KenticoCloud.Personalization.MVC;

var projectId = "569030c7-52a5-44f5-a243-c5285b3eb24e";
var apiKey = "<YOUR_PERSONALIZATION_API_KEY>";
PersonalizationClient client = new PersonalizationClient(apiKey, projectId);

VisitorsResponse response = await client.GetVisitorsInSegmentAsync("potential_job_candidates");
Visitor[] visitors = response.Visitors;
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: 569030c7-52a5-44f5-a243-c5285b3eb24e.

segment_codename
string
required

Codename of the segment. Example: potential_job_candidates. To view or edit the codename of the segment, open the segment in Kentico Cloud and click the Codename (#) button in the top right corner.

 

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/v3/segment/569030c7-52a5-44f5-a243-c5285b3eb24e/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

Tracking API

 

The Tracking API is a write-only REST API that 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/v3/track/<YOUR_PROJECT_ID>/.

At this time, requests to Tracking API do not need to be authenticated, but they must be made securely with HTTPS with TLS 1.2.

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.

  • Session IDs are exactly 16-character-long strings which can contain any number or letter.
  • User IDs are unrestricted strings with a maximum length of 20 characters.

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 and other information about the visitor.

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/v3/track/project_id/session
curl --request POST \
  --url https://engage-ket.kenticocloud.com/v3/track/14372844-0a5d-434a-8423-605b8a631623/session/ \
  --header 'content-type: application/json' \
  --data '
{
  "uid":"1111136b4af00000",
  "sid":"111114cc62300000"
}'
import KenticoCloud
 
let client = TrackingClient.init(projectId: "14372844-0a5d-434a-8423-605b8a631623")
client.startSession()
import { TrackingClient } from 'kentico-cloud-tracking';

const client = new TrackingClient({
  projectId: '14372844-0a5d-434a-8423-605b8a631623'
})

client.recordNewSession({
  sid: '111114cc62300000',
  uid: '1111136b4af00000',
})
  .getObservable()
  .subscribe(response => {
    console.log(response);
  });
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: 14372844-0a5d-434a-8423-605b8a631623.

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/v3/track/project_id/activity
curl --request POST \
  --url https://engage-ket.kenticocloud.com/v3/track/14372844-0a5d-434a-8423-605b8a631623/activity/ \
  --header 'content-type: application/json' \
  --data '
{
  "uid":"1111136b4af00000",
  "sid":"111114cc62300000",
  "codename": "Clicked_facebook_icon"
}'
import KenticoCloud
 
let client = TrackingClient.init(projectId: "9d2de312-9583-4860-84c2-320f1b16c846")
client.trackActivity(activityName: "Clicked_facebook_icon")
import { TrackingClient } from 'kentico-cloud-tracking';

const client = new TrackingClient({
  projectId: '14372844-0a5d-434a-8423-605b8a631623'
})

client.recordCustomActivity({
    sid: '111114cc62300000',
    uid: '1111136b4af00000'
  }, 
"Clicked_facebook_icon")
  .getObservable()
  .subscribe(response => {
    console.log(response);
  });
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: 14372844-0a5d-434a-8423-605b8a631623.

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.

codename
string
required

Codename of the custom activity. Example: Clicked_facebook_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

Create a contact profile

Submit the visitor's email address and other information.

 
posthttps://engage-ket.kenticocloud.com/v3/track/project_id/contact
curl --request POST \
  --url https://engage-ket.kenticocloud.com/v3/track/14372844-0a5d-434a-8423-605b8a631623/contact/ \
  --header 'content-type: application/json' \
  --data '
{
  "uid":"1111136b4af00000",
  "sid":"111114cc62300000",
  "email":"john.snow@wall.north",
  "name":"John Snow",
  "company":"Night's Watch",
  "phone":"444-256-487",
  "website":"http://gameofthrones.wikia.com/wiki/Jon_Snow"
}'
import KenticoCloud
 
let client = TrackingClient.init(projectId: "9d2de312-9583-4860-84c2-320f1b16c846")
client.addContact(email: "john.snow@wall.north")
import { TrackingClient } from 'kentico-cloud-tracking';

const client = new TrackingClient({
  projectId: '14372844-0a5d-434a-8423-605b8a631623'
})

client.createContactProfile({
  sid: '111114cc62300000',
  uid: '1111136b4af00000',
  email: "john.snow@wall.north",
  name: "John Snow",
  company: "Night's Watch",
  phone: "444-256-487",
  website: "http://gameofthrones.wikia.com/wiki/Jon_Snow"
})
  .getObservable()
  .subscribe(response => {
    console.log(response);
  });
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: 14372844-0a5d-434a-8423-605b8a631623.

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. Must be a valid email address. Example: john.snow@wall.north.

name
string

Name of the visitor. Example: John Snow.

company
string

Company of the visitor. Example: Night's Watch.

phone
string

Phone number of the visitor. Example: 444-256-487.

website
string

Website of the visitor. Must be a valid URL. Example: http://gameofthrones.wikia.com/wiki/Jon_Snow

 

Note: The maximum length of body parameters is 255 characters.

Record a session first

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

Creating a contact profile 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 visitor information).

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.

Suggest Edits

Migration API

 

Discontinuation notice

The Migration API will be fully operational until December 31, 2018. After this date, the API will stop working for all Kentico Cloud accounts. We recommend using the Content Management API instead.

The Kentico Cloud Migration API is a read-only REST API. The API is available only for Kentico Cloud projects stored in the West US data center.

The base URL for all requests is https://api.kenticocloud.com/draft/projects.

You can use the Migration API to import finished content items into a CMS of your choice, or perform a one-time export of larger amounts of content from Kentico Cloud.

Note: If you need to frequently deliver content, filter it and leverage content caching, we recommend using the Delivery API instead.

Suggest Edits

List projects

Retrieve a list of the projects available to you.

 
gethttps://api.kenticocloud.com/draft/projects
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "projects": [
    {
      "project_id": "917bb277-c013-45b9-a6fb-6ca925578f41",
      "name": "Empty Project"
    },
    {
      "project_id": "38af179c-40ba-42e7-a5ca-33b8cdcc0d45",
      "name": "Sample Project"
    }
  ]
}
 

Returns

A list of projects you have access to based on the provided API key in the Authorization header.

Suggest Edits

List content items

Retrieve a list of content items from your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/items
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "items": [
    {
      "item_id": "d686ae55-39ea-44e5-a40b-ba97d90e4dec",
      "type_id": "a77e9845-a2d9-4573-bbae-1e0a4cb70637",
      "workflow_status_id": "8eb2388e-682b-45ae-8405-5add40430dfd",
      "name": "Scheduled maintenance 2017/02",
      "sitemap_location": [],
      "last_modified": "2017-02-13T15:16:25.9473812Z",
      "elements": [
        {
          "value": "Another maintenance",
          "element_id": "93969f59-8130-83be-24d7-b7887ccc55a5",
          "name": "Title",
          "type": "text"
        },
        {
          "value": "<h1>Scheduled maintenance</h1>\n<p>Remember, we're doing this for you. It's going to be fine.</p>",
          "element_id": "c222f15f-a72f-3570-574a-975c21036920",
          "name": "Announcement text",
          "type": "rich_text"
        },
        {
          "value": [],
          "element_id": "c460263c-38b4-baff-5349-6440aae49716",
          "name": "Banner",
          "type": "asset"
        }
      ]
    },
    {
      "item_id": "307ba686-a05b-4678-b5ce-bff6fc558d27",
      "type_id": "a77e9845-a2d9-4573-bbae-1e0a4cb70637",
      "workflow_status_id": "8eb2388e-682b-45ae-8405-5add40430dfd",
      "name": "Scheduled maintenance 2017/04",
      "sitemap_location": [],
      "last_modified": "2017-02-13T15:00:18.8425411Z",
      "elements": [
        {
          "value": "Scheduled maintenance 2017/04",
          "element_id": "93969f59-8130-83be-24d7-b7887ccc55a5",
          "name": "Title",
          "type": "text"
        },
        {
          "value": "<h1>Scheduled maintenance</h1>\n<p>You can expect a temporary downtime in two months.&nbsp;</p>",
          "element_id": "c222f15f-a72f-3570-574a-975c21036920",
          "name": "Announcement text",
          "type": "rich_text"
        },
        {
          "value": [],
          "element_id": "c460263c-38b4-baff-5349-6440aae49716",
          "name": "Banner",
          "type": "asset"
        }
      ]
    }
  ],
  "pagination": {
    "total_item_count": 2,
    "page_item_count": 2,
    "page_count": 1,
    "current_page": 1
  }
}

Path Params

project_id
string
required

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

Query Params

sitemap_location
string

Filter the retrieved content items by their location in the project's sitemap. You can use this parameter multiple times to get items from several locations at once. Example: 9ee4e597-40c3-266d-5965-8d3e437b8eed. To retrieve a list of sitemap location IDs, see List sitemap locations.

workflow_status
string

Filter the retrieved content items by their workflow step. This way you can get, for example, only the approved content items by providing the ID of the specific workflow step. Example: 65e025db-1a04-4b9d-b366-408e09b58cb7. To retrieve a list of workflow status IDs, see List workflow steps.

content_type
string

Filter the retrieved content items by their content type. Example: 2e9b7cdd-e623-4918-a3f0-eb237878723c. To retrieve a list of content type IDs, see List content types.

 

Returns

An array of content item objects available in the specified project.

Suggest Edits

List content types

Retrieve a list of content types available in your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/types
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/types' \
--header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "types": [
    {
      "type_id": "b2c14f2c-6467-460b-a70b-bca17972a33a",
      "name": "About us",
      "elements": [
        {
          "element_id": "cff560dc-ed24-7036-cbb6-b7a1b61b196a",
          "name": "Facts",
          "type": "modular_content"
        }
      ]
    },
    {
      "type_id": "d9748663-f567-4c51-a922-c24a1d6b935a",
      "name": "Accessory",
      "elements": [
        {
          "element_id": "f9e2672c-5035-412e-3985-d6112b3781bd",
          "name": "Product name",
          "type": "text"
        },
        {
          "element_id": "51d63ac3-d40d-15ea-c219-be207714077c",
          "name": "Price",
          "type": "number"
        },
        {
          "element_id": "f0db12e6-86e4-8597-903b-c5984076d6b3",
          "name": "Image",
          "type": "asset"
        },
        {
          "element_id": "ab75ff46-b629-5ce5-aac9-79ed8a7b869c",
          "name": "Manufacturer",
          "type": "text"
        },
        {
          "taxonomy_group_id": "79b1c5b6-30bc-d076-a236-d9ec9f1ff01b",
          "element_id": "ef13b1f4-b558-f707-35a4-86146dbe4518",
          "name": "Product status",
          "type": "taxonomy"
        },
        {
          "element_id": "9740e2d0-87e8-52f5-ff4c-566fa00b1253",
          "name": "Short description",
          "type": "rich_text"
        },
        {
          "element_id": "1f961774-a589-4e21-9f8e-a8c4908ea476",
          "name": "Long description",
          "type": "rich_text"
        }
      ]
    },
    {
      "type_id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89",
      "name": "Article",
      "elements": [
        {
          "taxonomy_group_id": "f30c7f72-e9ab-8832-2a57-62944a038809",
          "element_id": "0a16b642-ac3e-584d-a45a-ba354a30b2bd",
          "name": "Personas",
          "type": "taxonomy"
        },
        {
          "element_id": "85d5efc6-f47e-2fde-a6f5-0950fe89ecd1",
          "name": "Title",
          "type": "text"
        },
        {
          "element_id": "62eb9881-e222-6b81-91d2-fdf052726414",
          "name": "Teaser image",
          "type": "asset"
        },
        {
          "element_id": "4ae5f7a9-fe1f-1e8c-bfec-d321455139c4",
          "name": "Post date",
          "type": "date_time"
        },
        {
          "element_id": "90550cbe-7bff-40a9-2947-9c81489fe562",
          "name": "Summary",
          "type": "text"
        },
        {
          "element_id": "108ed7c0-fc8c-c0ec-d0b5-5a8071408b54",
          "name": "Body Copy",
          "type": "rich_text"
        },
        {
          "element_id": "ee7c3687-b469-6c56-3ac6-c8dfdc8b58b5",
          "name": "Related articles",
          "type": "modular_content"
        },
        {
          "element_id": "5efb2425-5987-a4a6-a2d3-b14712b56e73",
          "name": "Meta keywords",
          "type": "text"
        },
        {
          "element_id": "b9dc537c-2518-e4f5-8325-ce4fce26171e",
          "name": "Meta description",
          "type": "text"
        }
      ]
    },
    {
      "type_id": "e097306b-3893-4a42-9973-2525fad14d66",
      "name": "Office",
      "elements": [
        {
          "element_id": "bb81a11d-886c-2a32-e480-29f01cea667f",
          "name": "Name",
          "type": "text"
        },
        {
          "element_id": "f7eb7ab2-4e41-aca0-7e93-dbbbdca330eb",
          "name": "Street",
          "type": "text"
        },
        {
          "element_id": "95477abc-d6b4-a6b3-5b72-c92763da55bf",
          "name": "City",
          "type": "text"
        },
        {
          "element_id": "4fbc7779-652d-7716-2673-7419aaaceed1",
          "name": "Country",
          "type": "text"
        },
        {
          "element_id": "08df2f10-52b8-d451-fab1-b6da8ddb3fd2",
          "name": "State",
          "type": "text"
        },
        {
          "element_id": "e7141da8-8792-a66d-d1c8-1fe704758393",
          "name": "Zip code",
          "type": "text"
        },
        {
          "element_id": "2ac708e2-cd0e-67b0-67f8-71725625dc6d",
          "name": "Phone",
          "type": "text"
        },
        {
          "element_id": "251dc38f-43a3-d924-a328-8708ecb00ef1",
          "name": "Email",
          "type": "text"
        }
      ]
    }
  ]
}

Path Params

project_id
string
required

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

 

Returns

An array of content type objects available in the specified project.

Suggest Edits

View a content item

Retrieve a specific content item from your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/items/item_id
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items/baccdc8b-7dd1-40ea-98bb-6a992b0558df' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "item_id": "baccdc8b-7dd1-40ea-98bb-6a992b0558df",
  "type_id": "929985ac-4aa5-436b-85a2-94c2d4fbbebd",
  "workflow_status_id": "13145328-b946-4e47-9c9d-6f40c7aaeaef",
  "name": "Colombia Carlos Imbachi",
  "sitemap_location": [
    "c6e04208-d6dd-1e25-f7ac-526daf042fb6"
  ],
  "last_modified": "2017-03-02T12:20:25.450198Z",
  "elements": [
    {
      "value": "Colombia Carlos Imbachi",
      "element_id": "edaec5c4-e653-9109-eb0d-fc40ccf3c810",
      "name": "Product name",
      "type": "text"
    },
    {
      "value": 10.5,
      "element_id": "624592dc-49b2-330a-7185-e1f2396ce90c",
      "name": "Price",
      "type": "number"
    },
    {
      "value": [
        {
          "asset_id": "80ee78c2-e6cb-4898-8053-91be9e763a4c",
          "name": "colombia.jpg",
          "type": "image/jpeg",
          "size": 75568,
          "last_modified": "2016-09-01T08:38:07.3800056Z",
          "create_download_link": "https://api.kenticocloud.com/draft/projects/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/assets/80ee78c2-e6cb-4898-8053-91be9e763a4c"
        }
      ],
      "element_id": "30ac3ccc-1e7f-1490-e1f6-915c64176a55",
      "name": "Image",
      "type": "asset"
    },
    {
      "value": "<p>The Colombian gold in the form of top quality coffee, also recognizable&nbsp;for its character. &nbsp;</p>",
      "images": [],
      "element_id": "b5a3263a-a1d7-92b7-865a-329f833285fa",
      "name": "Short description",
      "type": "rich_text"
    },
    {
      "value": "<p>As a part of our farmer-direct Colombia program, we bring you a special (above 88!) farm-specific number. We had some very special cupping samples sent to us straight from Colombia. And although they were all fantastic, this one really stood out from the others. Previously, we offered the \"First Place SCAA Coffee of the Year\" Carlos Imbachi. Just so you know what we're on about here, the famous Panama Esmeralda Especial Gesha ended up in 2nd place to Carlos Imbachi. Take this as another testament to the greatness and potential of Colombian coffee.</p>\n<figure data-image-id='9em8m'><img src=\"#\" alt=\"Colombia coffee\" data-image-id='9em8m'></figure><p>One cupping of this specialty was enough to recognize the unprecedented quality and character of this coffee. Mr. Imbachi's farm is located in the San Augustin region of Hulia, where he grows this coffee at an altitude of 5,700 feet.&nbsp;</p>",
      "images": [
        {
          "_id": "c52f0f99-d9bd-2598-d171-c37ab256fb7e",
          "asset": {
            "asset_id": "47b57724-b689-4865-9f12-521ddef2d025",
            "name": "kentico_cloud_rgb_small.png",
            "type": "image/png",
            "size": 8209,
            "last_modified": "2017-02-13T14:04:09.2146055Z",
            "create_download_link": "https://api.kenticocloud.com/draft/projects/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/assets/47b57724-b689-4865-9f12-521ddef2d025"
          }
        },
        {
          "_id": "9em8m",
          "asset": {
            "asset_id": "13e3857f-1fbb-4ec0-b7ec-3829d0325069",
            "name": "colombia.jpg",
            "type": "image/jpeg",
            "size": 75568,
            "last_modified": "2017-03-02T12:17:52.0565686Z",
            "create_download_link": "https://api.kenticocloud.com/draft/projects/38af179c-40ba-42e7-a5ca-33b8cdcc0d45/assets/13e3857f-1fbb-4ec0-b7ec-3829d0325069"
          }
        }
      ],
      "element_id": "d468a0aa-e0fa-0cae-41db-6e006bff2527",
      "name": "Long description",
      "type": "rich_text"
    },
    {
      "value": [],
      "element_id": "1ee64175-fde7-fc1e-5259-511a31c326c3",
      "name": "Product status",
      "type": "taxonomy"
    },
    {
      "value": "Finca Buenavista - Carlos Imbachi",
      "element_id": "e5cf103f-9b84-1ab0-29f1-fb5a1657c6f7",
      "name": "Farm",
      "type": "text"
    },
    {
      "value": "Colombia",
      "element_id": "6eec1918-378d-3b15-8b1a-19c5f0748321",
      "name": "Country",
      "type": "text"
    },
    {
      "value": "Caturra",
      "element_id": "301c6712-962f-b05a-6f6e-2f0e1e959039",
      "name": "Variety",
      "type": "text"
    },
    {
      "options": [
        "41cc0828-8a1c-3714-f86c-dee5faf09f1c"
      ],
      "element_id": "d5a32749-c934-e502-3e02-5512115735ce",
      "name": "Processing",
      "type": "multiplechoice"
    },
    {
      "value": "5700",
      "element_id": "23a772c0-0b2b-588d-9849-e29068701f03",
      "name": "Altitude",
      "type": "text"
    }
  ]
}

Path Params

project_id
string
required

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

item_id
string
required

The ID of the content item. Example: baccdc8b-7dd1-40ea-98bb-6a992b0558df.

 

Returns

A single content item object if a valid content item ID was specified.

Suggest Edits

List workflow steps

Retrieve a list of workflow steps in your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/workflow
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/workflow' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "statuses": [
    {
      "workflow_id": "88ac5e6e-1c5c-4638-96e1-0d61221ad5bf",
      "name": "Draft",
      "color": "red"
    },
    {
      "workflow_id": "13145328-b946-4e47-9c9d-6f40c7aaeaef",
      "name": "Review",
      "color": "yellow"
    },
    {
      "workflow_id": "48de7f2d-80de-4a8e-9efb-fc23bffbf75a",
      "name": "SEO verification",
      "color": "lime"
    },
    {
      "workflow_id": "99435d07-a9b7-4273-b439-a6e4bc125140",
      "name": "Ready for approval",
      "color": "teal"
    },
    {
      "workflow_id": "a1b9efa3-8270-47e4-8d8d-b182710d1e3b",
      "name": "Approved",
      "color": "blue"
    },
    {
      "workflow_id": "b4363ccd-8f21-45fd-a840-5843d7b7f008",
      "name": "Published",
      "color": "light-green"
    }
  ]
}

Path Params

project_id
string
required

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

 

Returns

A list of workflow steps defined in the specified project.

Suggest Edits

List sitemap locations

Retrieve a list of sitemap locations in your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/sitemap
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/sitemap' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "nodes": [
    {
      "sitemap_node_id": "778dd673-a341-41db-0735-a9d6bcede0b3",
      "name": "Home",
      "children": []
    },
    {
      "sitemap_node_id": "820563dc-6738-c641-cdd5-18fdcbebff9b",
      "name": "Products",
      "children": [
        {
          "sitemap_node_id": "c6e04208-d6dd-1e25-f7ac-526daf042fb6",
          "name": "Coffee",
          "children": []
        },
        {
          "sitemap_node_id": "0b7a84cd-8547-504e-b1aa-1ae8f7b6b675",
          "name": "Brewers",
          "children": []
        },
        {
          "sitemap_node_id": "fedea22c-4ab7-908e-6ac0-85b9730e3a6c",
          "name": "Accessories",
          "children": []
        },
        {
          "sitemap_node_id": "8fdb2025-e240-1a17-df13-b5914a681730",
          "name": "Grinders",
          "children": []
        }
      ]
    },
    {
      "sitemap_node_id": "a60fe91c-88ea-6990-fe3b-cf8f8504cd33",
      "name": "Cafes",
      "children": [
        {
          "sitemap_node_id": "6f648389-3bce-43ec-2529-e5ff3e12ebe7",
          "name": "North America",
          "children": []
        },
        {
          "sitemap_node_id": "ef86a740-9e4c-0b33-4275-ae78558e71a7",
          "name": "Europe",
          "children": []
        },
        {
          "sitemap_node_id": "98c9e0f1-b6f7-510d-522a-0d39fc62aa1a",
          "name": "Australia",
          "children": []
        }
      ]
    },
    {
      "sitemap_node_id": "45a123f3-1c55-c697-7dae-78369c8f1e2c",
      "name": "Articles",
      "children": []
    },
    {
      "sitemap_node_id": "22110d88-4b92-32a0-db61-9b8dbe401920",
      "name": "Offices",
      "children": []
    },
    {
      "sitemap_node_id": "398551ec-3f19-b177-2661-69bed4f35e20",
      "name": "About us",
      "children": []
    }
  ]
}

Path Params

project_id
string
required

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

 

Returns

A list of sitemap locations defined in the specified project. The API returns the complete sitemap hierarchy with all child sitemap locations.

Suggest Edits

List taxonomy groups

Retrieve a list of taxonomy groups in your project.

 
gethttps://api.kenticocloud.com/draft/projects/project_id/taxonomy
curl --request GET \
  --url 'https://api.kenticocloud.com/draft/projects/975bf280-fd91-488c-994c-2f04416e5ee3/taxonomy' \
  --header 'authorization: Bearer <YOUR_MIGRATION_API_KEY>' \
  --header 'content-type: application/json'
A binary file was returned

You couldn't be authenticated

{
  "taxonomy_groups": [
    {
      "taxonomy_id": "79b1c5b6-30bc-d076-a236-d9ec9f1ff01b",
      "name": "Product status",
      "nodes": [
        {
          "taxonomy_node_id": "6352c8bf-8024-9986-8373-35445e1f0d59",
          "name": "On sale",
          "children": []
        },
        {
          "taxonomy_node_id": "8d808da3-29de-e608-5699-8565687dd474",
          "name": "Bestseller",
          "children": []
        }
      ]
    },
    {
      "taxonomy_id": "f30c7f72-e9ab-8832-2a57-62944a038809",
      "name": "Personas",
      "nodes": [
        {
          "taxonomy_node_id": "6693ca6e-79e0-57e4-000d-d23d5ce8f656",
          "name": "Coffee expert",
          "children": [
            {
              "taxonomy_node_id": "6a372f43-ccd7-e524-6308-c2094e7b6596",
              "name": "Barista",
              "children": []
            },
            {
              "taxonomy_node_id": "cdf2f3c6-89e3-5df1-f7de-7179460bd6b4",
              "name": "Cafe owner",
              "children": []
            }
          ]
        },
        {
          "taxonomy_node_id": "ab2b73a3-473d-4232-0652-495598f5d670",
          "name": "Coffee enthusiast",
          "children": [
            {
              "taxonomy_node_id": "208a9095-1b92-10da-7627-75ae311935cf",
              "name": "Coffee lover",
              "children": []
            },
            {
              "taxonomy_node_id": "4fa27320-c363-3ebe-5ab5-b531300f053f",
              "name": "Coffee blogger",
              "children": []
            }
          ]
        }
      ]
    }
  ]
}

Path Params

project_id
string
required

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

 

Returns

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

Suggest Edits

Personal Data API

 

The Personal Data API is a REST API that retrieves or deletes data about your tracked visitors. You can use it to comply with GDPR and other data protection regulations by fulfilling the rights of your visitors to access and delete their personal information. It is not recommended to use the API for other purposes.

The base URL for all requests is https://personal-data-api.kenticocloud.com/v1/.

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

curl --request GET \
  --url https://personal-data-api.kenticocloud.com/v1/visitor/00e5492e-412a-0000-587a-c02f38134771/email/kroberts2y@godaddy.com/ \
  --header 'Authorization: Bearer <YOUR_PERSONAL_DATA_API_KEY>' \
  --header 'content-type: application/json'

User ID

Some Personal data API methods work with User ID, which identifies a specific visitor on your website. You can get this value either by parsing the content of a cookie stored by the tracking code in the browser or by calling a JavaScript method in the code of your website (this is the recommended way).

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

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

The method uses a callback with a string argument containing an ID of your visitor. Use the value when building a link to the REST interface. For more details, see Identifying visitors on websites.

Suggest Edits

Visitor data object model

Object model description of a single visitor data object.

 

When retrieving personal data of a tracked visitor, the Personal Data API returns a response object containing all trackedIds of a given visitor and a collection of visitorData objects.

The response object represents a complete export of all data about the specific visitor stored in Kentico Cloud. Please note that the response object may potentially change in the future as we make changes to our tracking algorithm.

For more information about the tracked data, see Personal Data in Kentico Cloud.

Note: A visitor can be tracked using multiple rawUids in case they visit your website from multiple devices/browsers. If the visitor submits the same email address again from a different device, the two visitor profiles are merged together. The trackedIds property represents all rawUids used to track that one visitor.

Visitor data object

Attribute Description Type Notes
uid Internal ID of the visitor in GUID form string Example: 8b6eb341-f970-5722-49dd-4ce0558833b8.
projectId Unique identifier of the Kentico Cloud project string
email Email address of the visitor string
name Name of the visitor string
company Company of the visitor string
website Website of the visitor string
phone Phone number of the visitor string
firstVisit First visit of the visitor string ISO-8601 formatted date/time.
lastVisit Last visit of the visitor string ISO-8601 formatted date/time.
lastUpdate Last time the visitor data was updated string ISO-8601 formatted date/time.
anonymous Anonymity of the visitor boolean true if the visitor has no email address.
source A website from which the visitor got to your website string
sourceApp Your website or app string
photoUrl Url of the visitor's profile picture string
sessionRecords Records of the visitor's individual sessions collection of Session record objects Session is defined as 30 minutes of continuous visitor activity.
emailHash Hash of the visitor's email address string
rawUid External ID of the visitor used in the tracking code and Personalization API string Example: 1a7379c4026d4614.

Session record object (visitor data)

A session is defined as 30 minutes of continuous visitor activity. Example:

  • If a visitor comes to your website and then clicks on an article 29 minutes later, it's considered part of the same session.
  • If they then click on a different article after 31 minutes of inactivity, it's considered a start of a new session.
Attribute Description Type Notes
uid Internal ID of the visitor in GUID form string Example: 8b6eb341-f970-5722-49dd-4ce0558833b8.
sid Internal ID of the session in GUID form string Example: 5688f68f-4dd1-2236-e93a-c25900e7f4dd
created Time when the session was created string ISO-8601 formatted date/time.
referrer Absolute URL of the website from which the visit originated string
mobile Whether the visitor used a mobile or a desktop device boolean
browserName Name of the visitor's browser string
browserVersion Version of the visitor's browser boolean
osName Name of the visitor's operating system string
osVersion Version of the visitor's operating system string
sourceApp Your website or app string
ipHash Hash of the visitor's IP address string
actions Actions performed by the visitor on your website collection of Action objects Example: Page visit, Form submit, etc.
customActivities Custom activities performed by the visitor collection of Custom activity objects See Tracking custom activities for more details.
trackingIP Information derived from the visitor's IP address Tracking IP object
rawSid External ID of the session used in the tracking code and Personalization API string Example: a9e8bf8bd411431f.

Action object (session record)

Represents an action done by a visitor.

Attribute Description Type Notes
actionType Type of the performed action string Possible values: pageVisit, formSubmit.
pageUrl Url of the page on which the action was performed string
pageTitle Title of the page on which the action was performed string
created Time when the action was performed string ISO-8601 formatted date/time.
sid Internal ID of the session in GUID form string
uid Internal ID of the visitor in GUID form string

Custom activity object (session record)

Represents a custom activity performed by a visitor.

Attribute Description Type Notes
uid Internal ID of the visitor in GUID form string
sid Internal ID of the session in GUID form string
name Name of the performed custom activity string
created Time when the activity was performed string ISO-8601 formatted date/time.

Tracking IP object (session record)

Represents data extracted from the visitor's IP address.

Attribute Description Type Notes
city City of the visitor string
country Country of the visitor string
countryCode Code of the country string
lat Lattitude string
lon Longitude string
regionName Name of the region string
ipHash Hash of the visitor's IP address string

Example: Visitor data object

{
  "visitorData":[
    {
      "uid":"8b6eb341-f970-5722-49dd-4ce0558833b8",
      "projectId":"00e5492e-412a-0000-587a-c02f38134771",
      "email":"kroberts2y@godaddy.com",
      "name":"Kathleen Roberts",
      "company":null,
      "website":null,
      "phone":null,
      "firstVisit":"2018-05-03T08:03:06.6304375+00:00",
      "created":"2018-05-03T08:03:06.6304375+00:00",
      "lastVisit":"2018-05-03T08:03:06.6304375+00:00",
      "lastUpdate":"2018-05-03T08:09:06.6304375+00:00",
      "anonymous":false,
      "source":"https://jalbum.net",
      "sourceApp":"https://engage.demo.com",
      "photoUrl":null,
      "sessionRecords":{
        "5688f68f-4dd1-2236-e93a-c25900e7f4dd":{
          "uid":"8b6eb341-f970-5722-49dd-4ce0558833b8",
          "sid":"5688f68f-4dd1-2236-e93a-c25900e7f4dd",
          "created":"2018-05-03T08:03:06.6304375+00:00",
          "referrer":"https://jalbum.net",
          "mobile":false,
          "browserName":"Chrome",
          "browserVersion":"65",
          "osName":"Windows",
          "osVersion":"10",
          "sourceApp":"https://engage.demo.com",
          "ipHash":"b188ffa9-6ab8-af8c-8b4b-69092a160bf5",
          "actions":[
            {
              "actionType":"FormSubmit",
              "pageUrl":"/partnership",
              "pageTitle":"Partnership - Dancing Goat",
              "created":"2018-05-03T08:09:06.6304375+00:00",
              "sid":"5688f68f-4dd1-2236-e93a-c25900e7f4dd",
              "uid":"8b6eb341-f970-5722-49dd-4ce0558833b8"
            }
          ],
          "customActivities":[

          ],
          "trackingIp":{
            "city":"Watulumbung",
            "country":"Indonesia",
            "countryCode":"ID",
            "lat":"-7.0052",
            "lon":"111.512",
            "regionName":"",
            "ipHash":"b188ffa9-6ab8-af8c-8b4b-69092a160bf5"
          },
          "rawSid":"a9e8bf8bd411431f"
        }
      },
      "emailHash":"067d55fb-4ce0-7794-fe37-df0cacc08748",
      "rawUid":"1a7379c4026d4614"
    }
  ],
  "trackedIds":[
    "1a7379c4026d4614"
  ]
}
Suggest Edits

View personal data of a visitor by ID

 
gethttps://personal-data-api.kenticocloud.com/v1/visitor/project_id/uid/uid
curl --request GET \
  --url https://personal-data-api.kenticocloud.com/v1/visitor/00e5492e-412a-0000-587a-c02f38134771/uid/1a7379c4026d4614/ \
  --header 'Authorization: Bearer <YOUR_PERSONAL_DATA_API_KEY>' \
  --header 'content-type: application/json'
var projectId = new Guid("<YOUR_PROJECT_ID");
var apiKey = "<YOUR_PERSONAL_DATA_API_KEY>";

client = new PersonalDataClient(apiKey, projectId);
var response = await client.GetByUidAsync("1a7379c4026d4614");
A binary file was returned

You couldn't be authenticated

{
  "visitorData":[
    {
      "uid":"8b6eb341-f970-5722-49dd-4ce0558833b8",
      "projectId":"00e5492e-412a-0000-587a-c02f38134771",
      "email":"kroberts2y@godaddy.com",
      "name":"Kathleen Roberts",
      "company":null,
      "website":null,
      "phone":null,
      "firstVisit":"2018-05-03T08:03:06.6304375+00:00",
      "created":"2018-05-03T08:03:06.6304375+00:00",
      "lastVisit":"2018-05-03T08:03:06.6304375+00:00",
      "lastUpdate":"2018-05-03T08:09:06.6304375+00:00",
      "anonymous":false,
      "source":"https://jalbum.net",
      "sourceApp":"https://engage.demo.com",
      "photoUrl":null,
      "sessionRecords":{
        "5688f68f-4dd1-2236-e93a-c25900e7f4dd":{
          "uid":"8b6eb341-f970-5722-49dd-4ce0558833b8",
          "sid":"5688f68f-4dd1-2236-e93a-c25900e7f4dd",
          "created":"2018-05-03T08:03:06.6304375+00:00",
          "referrer":"https://jalbum.net",
          "mobile":false,
          "browserName":"Chrome",
          "browserVersion":"65",
          "osName":"Windows",
          "osVersion":"10",
          "sourceApp":"https://engage.demo.com",
          "ipHash":"b188ffa9-6ab8-af8c-8b4b-69092a160bf5",
          "actions":[
            {
              "actionType":"FormSubmit",
              "pageUrl":"/partnership",
              "pageTitle":"Partnership - Dancing Goat",
              "created":"2018-05-03T08:09:06.6304375+00:00",
              "sid":"5688f68f-4dd1-2236-e93a-c25900e7f4dd",
              "uid":"8b6eb341-f970-5722-49dd-4ce0558833b8"
            }
          ],
          "customActivities":[

          ],
          "trackingIp":{
            "city":"Watulumbung",
            "country":"Indonesia",
            "countryCode":"ID",
            "lat":"-7.0052",
            "lon":"111.512",
            "regionName":"",
            "ipHash":"b188ffa9-6ab8-af8c-8b4b-69092a160bf5"
          },
          "rawSid":"a9e8bf8bd411431f"
        }
      },
      "emailHash":"067d55fb-4ce0-7794-fe37-df0cacc08748",
      "rawUid":"1a7379c4026d4614"
    }
  ],
  "trackedIds":[
    "1a7379c4026d4614"
  ]
}
Visitor was not found or doesn't exist.

Path Params

project_id
string
required

The ID of your project. Example: 00e5492e-412a-0000-587a-c02f38134771

uid
string
required

User ID of a visitor. Example: 1a7379c4026d4614

 

Returns

All information about the specified visitor stored in Kentico Cloud. For more details, see Personal data in Kentico Cloud.

Suggest Edits

View personal data of a visitor by email

 
gethttps://personal-data-api.kenticocloud.com/v1/visitor/project_id/email/email
curl --request GET \
  --url https://personal-data-api.kenticocloud.com/v1/visitor/00e5492e-412a-0000-587a-c02f38134771/email/kroberts2y@godaddy.com/ \
  --header 'Authorization: Bearer <YOUR_PERSONAL_DATA_API_KEY>' \
  --header 'content-type: application/json'
var projectId = new Guid("<YOUR_PROJECT_ID");
var apiKey = "<YOUR_PERSONAL_DATA_API_KEY>";

client = new PersonalDataClient(apiKey, projectId);
var response = await client.GetByEmailAsync("kroberts2y@godaddy.com");
A binary file was returned

You couldn't be authenticated