The Management API is a secure REST API that provides read/write access to your Kentico Kontent projects.
Use the API to migrate your existing content into your Kentico Kontent project, or update content in unpublished content items. The API cannot be used on published content unless you create new versions of the content items first, either in UI or through the Management API.
When retrieving and updating content via the Management 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/v1/projects/<YOUR_PROJECT_ID>
.
All requests to the API must be made securely with HTTPS with TLS 1.2 and authenticated with a valid API key. Requests to the API are rate limited and uncached.
API requests limits
The requests made to the 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 --request GET \ --url https://manage.kontent.ai/v1/projects/<YOUR_PROJECT_ID>/items \ --header 'Authorization: Bearer <YOUR_API_KEY>' \ --header 'Content-type: application/json'
The Management API does not provide any content filtering options and is not optimized for content delivery. If you need to deliver larger amounts of content, filter it, and leverage content caching, we recommend using the Delivery API instead.
To work with the Management API, send your requests over HTTPS and authenticate using the Authorization
header in the following format: Authorization: Bearer <YOUR_API_KEY>
.
To get your API key for the Management API, go to Kentico Kontent > Project settings > API keys. The API key provides access to a single Kentico Kontent project. You will need different API keys for each of your projects.
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.
Security Scheme Type | HTTP |
---|---|
HTTP Authorization Scheme | bearer |
Bearer format | "Bearer <YOUR_API_KEY>" |
We offer a .NET SDK to help you work with the API. However, no SDK is required to use the API.
The state of the Management API may change in the future, however, the majority won't be breaking changes. To help you create more robust scripts and integrations, we've prepared a list of general changes to the API that we don't consider breaking. We recommend you read through the list to ensure you don't rely on a state that might change in the future.
In general, the non-breaking changes include adding functionality or changes in order of the returned data. More specifically, the following are NOT breaking changes:
The Management API returns standard HTTP status codes to indicate success or failure of a request. In general, status codes in the 2xx
range indicate a successful request, status codes in the 4xx
range indicate errors caused by an incorrect input (for example, providing incorrect API key), and status codes in the 5xx
range indicate an error on our side.
HTTP status code |
Description |
|
The request was not understood. Check your request for missing required parameters or invalid query parameter values. |
|
The provided API key is invalid or missing. |
|
The provided API key is invalid for the requested project. |
|
The requested resource doesn't exist. Try checking the path for typos. |
|
The requested HTTP method is not supported for the specified resource. Try performing a GET request. |
|
The request could not be completed due to a conflict with the current state of the specified resource. For example, this may occur if a resource is modified via multiple requests at the same time. |
|
The rate limit for the API has been exceeded. Try your request again after a few seconds. |
|
Something went wrong on our side. Try your request again after a few seconds and use a retry policy. |
For troubleshooting failed requests, the API provides error messages defined in a consumable format to help you identify and fix the issue.
request_id required | string <uuid> The performed request's unique ID. |
error_code required | integer <int32> >= 1 The specific internal code for the type of error. Only useful for finding patterns among error requests. |
message required | string The error message explaining why the error occurred. |
validation_errors | Array of objects A list of specific issues that occurred when processing the request. |
{- "request_id": "|797b0d5e2cecaf41b17a5aa4ca1b9276.d1956d1_",
- "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": "No patch operations were provided, provide at least one operation."
}
]
}
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.
By default, the API keys for the 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 after a short while. For requests made with a revoked API key, you'll receive the 403 Unauthorized
error response.
{ "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." }
Friendly reminder
5 days before the API key expires, we will send a notification email to users with the Manage APIs permission.
Rate limits specify the number of requests you or your application can make to the 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 Management API enforces the following rate limits:
These limits apply to each API key for the Management API.
Patience is a virtue
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.
{ "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 identify 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 can be identified by one of three properties:
18b43cc5-f4fd-0172-842b-3ae2c878cf6f
object_codename
custom-object-identifier
When editing codenames, the new codenames must meet the following conditions:
This means the following applies when codenames are generated automatically:
_
.n
.The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.
id | string <uuid> The referenced object's internal ID. |
codename | string [ 1 .. 60 ] characters The referenced object's codename. |
external_id | string non-empty The referenced object's external ID. |
{- "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
}
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 Management 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. References to non-existent objects will be stored and retrieved via the Management API as internal IDs.
To check whether your project contains any references to not-yet-created objects, see how to validate project content.
Referencing objects that are not in your project yet
The Management API supports referencing of non-existent objects in the following elements:
To learn more, see how to import linked content to your project.
If you use external IDs to reference non-existent objects in your elements, the referenced objects won't be shown in the UI. This is because the system cannot find those objects. The referenced assets and content items will be displayed after you create them with their specific external IDs via the Management API.
To add the missing objects, see:
To manage content items via the Management API, you need to send requests to URIs based on the following patterns:
<base_URL>/items/<content_item_id>
<base_URL>/items/codename/<content_item_codename>
<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.
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.
id | string <uuid> The content item's internal ID. |
name required | string [ 1 .. 200 ] characters The content item's display name. |
codename | string [ 1 .. 60 ] characters The content item's codename. Unless set while creating the content item, it is initially generated from the item's |
type required | object Reference to the item's content type. |
sitemap_locations | Array of objects Deprecated The content item's location (or locations) in the project sitemap. |
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. External IDs cannot be upserted into existing items. |
last_modified | string <date-time> The ISO-8601 formatted date and time of the last change to the content item. Workflows and values Moving content items through workflow (either in UI or through the API) doesn't affect the |
{- "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
- "name": "My article",
- "codename": "my_article",
- "type": {
- "id": "d89b6348-7cdc-444a-8e1e-adacb564f2a2"
}, - "sitemap_locations": [ ],
- "external_id": "custom-identifier-for-my-article",
- "last_modified": "2019-04-04T13:45:30.7692802Z"
}
Management API v1
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.
project_id required | string Identifies your project. |
The content item to be added.
name required | string [ 1 .. 200 ] characters The content item's display name. |
codename | string [ 1 .. 60 ] characters The content item's codename. Unless set while creating the content item, it is initially generated from the item's |
type required | object Reference to the item's content type. |
sitemap_locations | Array of objects Deprecated The content item's location (or locations) in the project sitemap. |
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. External IDs cannot be upserted into existing items. |
The created content item object.
The specified request body is invalid.
{- "name": "My article",
- "codename": "my_article_2",
- "type": {
- "codename": "article"
}, - "external_id": "my-1337-article"
}
{- "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
- "name": "My article",
- "codename": "my_article_2",
- "type": {
- "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
}, - "sitemap_locations": [ ],
- "external_id": "my-1337-article",
- "last_modified": "2020-04-04T13:45:30.7692802Z"
}
Management API v1
Retrieve a dynamically paginated list of content items.
project_id required | string Identifies your project. |
continuationToken | string Determines the page of results to retrieve. To get the next page, see the pagination object in the response and set the |