Skip navigation

Management API v1 (Deprecated)

Download OpenAPI specification:Download

Introduction

Use Management API v2

From July 1, 2022, the Management API version 1 has been deprecated. The deprecation period will last six months after which we plan to sunset version 1. We recommend that you build your new scripts and integrations around the Management API v2.

If you're using Management API version 1 for your operations, check our Management API migration guidelines. Use the guidelines to transition your apps and services to Management API version 2.

With version 2 of the Management API, you can do everything from version 1 and more. Version 1 supports management of your assets, items, and variants. With version 2, you can manage your whole project and automate more than just content operations.

The Management API v1 is a secure REST API that provides read/write access to your Kontent projects. Use the API to import, update, or delete assets, content items, and language variants in your project.

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.

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

Need content filtering?

If you need to filter content and deliver it to your apps, we recommend using the Delivery REST API or Delivery GraphQL API.

Authentication

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 Kontent > Project settings > API keys. The API key provides access to a single Kontent project. You will need different API keys for each of your projects.

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.

Security Scheme TypeHTTP
HTTP Authorization Schemebearer
Bearer format"Bearer <YOUR_API_KEY>"

Migration guidelines

If you're planning to migrate from Management API v1 to Management API v2, these guidelines will help you understand the differences between the Management API versions and the changes you'll need to make.

Changes between the API versions

With Management API v2, you can perform the same operations as with version 1. Here's an overview of the operations in version 1. Similarities with version 2 are marked with ✔ and the differences with ⚠.

  • ✔ Create, read, update, and delete assets
  • ✔ Create, read, update, and delete content items
  • ⚠ Create, read, update, and delete language variants
  • ✔ Identify objects with references
  • ✔ Read project information
  • ✔ Validate project

The language variant object changed in version 2. Let's see how the language variant objects differ.

The new language variant object

In version 1, the language variant's elements property is an object. Each property of the elements object represents an element with the element's value. Here's the language variant object in Management API v1.

item
object

Reference to the content item.

elements
required
object

List of elements as defined in the item's content type.

language
object

Reference to the language of the variant.

The default language will always have the ID of 00000000-0000-0000-0000-000000000000.

last_modified
string <date-time>

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

Copy
Expand all Collapse all
{
  • "item":
    {
    • "id": "b69ed774-8fb2-4413-8d12-d4c193a66f7a"
    },
  • "elements":
    {
    • "title": "Write like a pro",
    • "content": "<p>Lorem ipsum dolor sit amet.</p>",
    • "author":
      [
      • {
        • "id": "7ada5ba4-ce00-435d-b233-83364d33705e"
        }
      ]
    },
  • "language":
    {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "last_modified": "2019-02-27T19:08:25.404Z"
}

In version 2, the language variant's elements property is an array of objects. Each of those objects consists of the element and value properties. Here's the language variant object in Management API v2.

elements
required
Array of AssetElement (object) or CustomElement (object) or DateTimeElement (object) or LinkedItemsElement (object) or MultipleChoiceElement (object) or NumberElement (object) or RichTextElement (object) or SubpagesElement (object) or TaxonomyElement (object) or TextElement (object) or UrlSlugElement (object)

List of elements as defined in the item's content type.

workflow
object

Specifies the variant's current workflow and workflow step.

workflow_step
object
Deprecated

Reference to the variant's current workflow step.

item
object

Reference to the content item.

language
object

Reference to the language of the variant.

The default language will always have the ID of 00000000-0000-0000-0000-000000000000.

last_modified
string <date-time>

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

Copy
Expand all Collapse all
{
  • "elements":
    [
    • {
      • "element":
        {
        • "id": "c7c3b834-2222-5677-89c4-b46f04489109"
        },
      • "value": "Text element value"
      },
    • {
      • "mode": "custom",
      • "element":
        {
        • "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
        },
      • "value": "custom-url-slug-value"
      }
    ],
  • "workflow":
    {
    • "workflow_identifier":
      {
      • "id": "06ea628e-4ec7-4991-91e4-1412995151ee"
      },
    • "step_identifier":
      {
      • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
      }
    },
  • "workflow_step":
    {
    • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
    },
  • "item":
    {
    • "id": "82ef61f4-ccee-42ac-95e2-1a44beda9625"
    },
  • "language":
    {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "last_modified": "2020-02-27T19:08:25.404Z"
}

Adjust to Management API v2

We recommend that you use the latest version of the Management SDK for your apps and scripts. We provide JavaScript and .NET SDKs.

You can find examples of how to work with the new language variant object in the SDK documentation on GitHub:

Try the API with Postman

Try out any of the Kontent.ai APIs with Postman! 📫 The Postman collection is regularly updated and contains endpoints for all Kontent.ai REST APIs, just like in the API references.

SDKs

We don't provide any SDKs for Management API v1. However, you don't need an SDK to use the API.

To use SDKs with the Management API, check out the .NET and JS SDKs for Management API v2.

API key scope and validity

By default, the API keys for the Management API are valid for 4,000 days. The scope of the API keys is per environment per user. This means you need a separate API key for each of your environments.

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.

  • 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 Kontent.ai." }

Friendly reminder

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

API limitations

API requests limit

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

Rate limiting

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

By default, the Management API enforces the following rate limits:

  • 10 requests per second
  • 400 requests per minute

The scope of these rate limits is per environment. Requests made with multiple API keys from a single environment count against a single rate limit.

These limits apply to requests made to a single environment.

Avoid parallel requests

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.

Errors

The API returns standard HTTP status codes to indicate the 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 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.

429 Too Many Requests

The rate limit for the API has been exceeded. Try your request again after a few seconds as specified in the Retry-After header.

5xx Internal Error or Service Unavailable

Something went wrong on our side. Try your request again after a few seconds and use a retry policy.

Resolving errors

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

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.

Copy
Expand all Collapse all
{
  • "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, contact us with the response status and the request ID you get in the error response.

References

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:

  1. Its internal ID, such as 18b43cc5-f4fd-0172-842b-3ae2c878cf6f
    • Generated by the system automatically.
    • Unique per object type such as content item, content type, and other.
    • Can be used to specify any object.
  2. Its codename, such as object_codename
    • Initially generated from the object's display name.
    • Unique per object type such as content item, content type, and other.
    • Can be used to specify most objects.
  3. Its external ID, such as custom-object-identifier
    • Specified manually when creating the object through the Management API. The external ID cannot be changed later.
    • Unique per object type within its parent object scope. For example, the uniqueness applies to elements within a content type, content types within a project, content items within a project, and so on. This also means you can have a content type and its element with the same external ID.
    • Can be used to specify custom identifiers for user-created objects such as assets, content items, content types and more.

Rules for codenames

When editing codenames, the new codenames must meet the following conditions:

  • Only lowercase letters, numbers, and underscores are permitted.
  • Codenames must start with a letter or an underscore and have at least one character.
  • Codenames are usually limited to 60 characters, but longer codenames are allowed for multiple choice options and taxonomy terms.
  • Codenames of elements within a snippet must be prefixed with the snippet's codename.
  • Codenames must be unique per object type. This applies to, for example, every element within a content type, every content type within a project, every content item within a project, and so on.

This means the following applies when codenames are generated automatically:

  • All letters are made lowercase.
  • All forbidden characters are replaced by _.
  • For any names that start with a number, the codename will start with n.
  • Codenames that duplicate another codename will have a random string attached to the end.
  • Codenames of elements within a snippet will be prefixed with the snippet's codename.
  • Codenames will be cut off at the character limit.

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.

id
string <uuid>

The referenced object's internal ID.

codename
string

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id
string

The referenced object's external ID. The value of the external_id property must not contain the following characters: /, ., ;.

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

External IDs for imported content

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.

Missing objects in the UI

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:

Assets

Assets in Kontent.ai 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.

Adding assets is a 2-step process

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

Binary files that are not used by any assets will not be visible in the Kontent.ai UI.

Asset object

id
required
string <uuid>

The asset's internal ID.

file_name
required
string