Skip navigation

Content Management API v2

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

Introduction

This API is in BETA

For planned features, see our Roadmap. If you have any feedback on the API, let us know using the chat button in the bottom-right corner.

For the current stable version of CM API, see Content Management API v1.

Premium feature 

The Content Management API requires a Professional plan or higher.

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

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 Kontent user interface. Learn how to import content via the API by taking the tutorial on Importing to Kentico Kontent.

The base URL for all requests is https://manage.kontent.ai/v2/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.

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 Kontent website.

  • cURL
curl --request GET \ --url https://manage.kontent.ai/v2/projects/975bf280-fd91-488c-994c-2f04416e5ee3/items \ --header 'Authorization: Bearer <YOUR_API_KEY>' \ --header 'Content-type: application/json'

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.

Authentication

To work with the Content Management API, send your requests over HTTPS and authenticate using the Authorization header in the following format: Authorization: Bearer <YOUR_API_KEY>.

Bearer

This API uses OAuth 2.0 bearer token (API key) to authorize requests. Requests with an incorrect or missing Authorization header will fail with an error.

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

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "Bearer <YOUR_API_KEY>"

Errors

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

Error codes summary

Status code

Description

400 Bad Request

The request was not understood. Check your request for a missing required parameter or an invalid query parameter value.

401 Unauthorized

The provided API key is invalid or missing.

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 API provides error messages defined in a consumable format to help you identify and fix the issue.

error_code
required
integer <int32> [ 100 .. 500 ]

The specific code for the type of error.

message
required
string

The error message explaining why the error occurred.

request_id
required
string <uuid>

The performed request's unique ID.

validation_errors
Array of objects

A list of specific issues that occurred when processing the request.

Copy
Expand all Collapse all
{
  • "request_id": "string",
  • "error_code": 100,
  • "message": "string",
  • "validation_errors":
    [
    • {
      }
    ]
}

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

API key scope and validity

By default, the API keys for the Content Management API are valid for 4,000 days. 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 of the user who generated it. Operations performed with the key will show in your version history as changes made by the specific user.

If you regenerate the API key before its expiration date, the system will revoke the previous API key. For requests made with a revoked API key, you'll receive the 403 Unauthorized error response.

  • JSON
{ "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 Kontent app." }

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

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 Content Management API enforces the following rate limits

  • 10 requests per second
  • 400 requests per minute
  • 15000 requests per hour

These limits apply to each API key for the Content Management API.

Note: We strongly advise against making multiple requests to the API in parallel. Doing so may cause unpredictable behavior and lead to inconsistencies in your content. We recommend that you wait for each request to finish before sending another one.

When you reach the limit of a specific time window, the API will reject the request and respond with the 429 HTTP error.

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

The error 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.

References

References are identifiers of objects within your project. For example, you can use references to specify content types, content items, languages, and more.

When specifying references to objects, the object must be identified in one of three ways:

  1. Internal ID of the object, such as 18b43cc5-f4fd-0172-842b-3ae2c878cf6f
    • Generated by the system automatically.
    • Can be used to specify any object.
  2. Codename of the object, such as item_codename
    • Initially generated from the display name of an object.
    • Can be used to specify any object, expect for workflow steps which don't have codenames.
  3. External ID of the object, such as object-id-from-another-system
    • Specified by the user when creating the object through the CM API. The external ID of an object cannot be changed later.
    • Can be used to specify user-created assets, content items, content types, content groups, elements, languages, taxonomy groups and taxonomy terms.

Reference object

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

external_id
string non-empty

The referenced object's external ID.

id
string <uuid>

The referenced object's internal ID.

Copy
Expand all Collapse all
{
  • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
}

External IDs for imported content

When adding new content types to your project, content groups must be referenced by their external IDs. 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 UI only after you add them as assets via the CM 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 reference objects that don't yet exist in the project and add the objects via the API later.

To check whether your project contains any references to not-yet-created objects, see how to validate project content.

Note: References to non-existent objects will be stored and retrieved via the CM API as internal IDs.

Referencing objects that are not in your project yet

The Content Management API supports referencing of non-existent objects in the following elements:

See how to import linked content to learn more.

Missing objects in the UI

If you reference non-existent objects by external IDs in your elements, the referenced objects won't be shown in the user interface because the system cannot find those objects. The referenced assets, content items, and taxonomy terms will be displayed after you create them with their specific external IDs via the CM API.

To add the missing objects, see:

Content items

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

The content item object contains metadata about your content, such as the name of the content item and when the item was last modified. 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.

codename
required
string [ 1 .. 50 ] characters

The content item's codename. Generated from the content item's name.

id
required
string <uuid>

The content item's internal ID.

last_modified
required
string <date-time>

The ISO-8601 formatted date and time of the last change to the content item.

Note: Moving content items through workflow doesn't affect the last_modified value.

name
required
string [ 1 .. 50 ] characters

The content item's display name.

type
required
object

Reference to the item's content type.

external_id
string

The content item's external ID. The external ID can be used as a unique identifier to retrieve content from a different system.

Note: External IDs cannot be upserted into exisiting items.

sitemap_locations
Array of objects

The content item's location (or locations) in the project sitemap.

Deprecation notice

Sitemap has been deprecated since April 2019. The sitemap_locations property is a legacy property.

Copy
Expand all Collapse all
{
  • "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474",
  • "name": "On Roasts",
  • "codename": "on_roasts",
  • "type":
    {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "sitemap_locations":
    [
    • {
      }
    ],
  • "external_id": "my-item-identifier",
  • "last_modified": "2019-04-04T13:45:30.7692802Z"
}

Add a content item Beta

post /{project_id}/items
See full URL

Content Management API v2 (BETA)

https://manage.kontent.ai/v2/projects/{project_id}/items

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 property to set a custom identifier for the new content item.

Authorizations:
path Parameters
project_id
required
string
Example: 975bf280-fd91-488c-994c-2f04416e5ee3

Identifies your project.

Request Body schema: application/json

The content item to be added.

name
required
string [ 1 .. 50 ] characters

The content item's display name.

type
required
object

Reference to the item's content type.

external_id
string

The content item's external ID. The external ID can be used as a unique identifier to retrieve content from a different system.

Note: External IDs cannot be upserted into exisiting items.

sitemap_locations
Array of objects

The content item's location (or locations) in the project sitemap.

Deprecation notice

Sitemap has been deprecated since April 2019. The sitemap_locations property is a legacy property.

Responses

201

The content item was created.

400

The specified request body is invalid.

429

The API rate limit has been exceeded.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "On Roasts",
  • "type":
    {
    • "codename": "article"
    },
  • "external_id": "59713"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474",
  • "name": "On Roasts",
  • "codename": "on_roasts",
  • "type":
    {
    • "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
    },
  • "sitemap_locations":
    [
    • {
      }
    ],
  • "external_id": "59713",
  • "last_modified": "2017-04-04T13:45:30.7692802Z"
}

List content items Beta

get /{project_id}/items
See full URL

Content Management API v2 (BETA)

https://manage.kontent.ai/v2/projects/{project_id}/items

Retrieve a dynamically paginated list of content items.

Authorizations:
path Parameters
project_id
required
string
Example: 975bf280-fd91-488c-994c-2f04416e5ee3

Identifies your project.

query Parameters
continuationToken
string
Deprecated
Example: continuationToken=MTAw

Determines the page of results to retrieve.

To get the next page, see the pagination object in the response and set the continuationToken parameter to the value of the continuation_token property.

header Parameters
x-continuation
string

Determines the page of results to retrieve.

To get the next page, see the pagination object in the response and set the x-continuation parameter to the value of the continuation_token property.

Responses

200

A dynamically paginated list of content items.

429

The API rate limit has been exceeded.

Request samples

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "items":
    [
    • {
      },
    • {
      },
    • {
      }
    ],
}

Retrieve a content item Beta

get /{project_id}/items/{item_identifier}
See full URL

Content Management API v2 (BETA)

https://manage.kontent.ai/v2/projects/{project_id}/items/{item_identifier}

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

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

Authorizations:
path Parameters