Management API is a secure REST API that provides read and write access to your Kontent.ai projects and environments. If you'd like to manage subscriptions and users via API, use Subscription API.

Use Management API v2 to manage your content & assets, content model, environment settings, and users.

The base URL for all requests to Management API is https://manage.kontent.ai/v2. Requests must be made securely over HTTPS and authenticated with a valid personal API key. Requests to the API are rate limited and uncached.

curl --request GET 
  --url https://manage.kontent.ai/v2/projects/<YOUR_ENVIRONMENT_ID>/items 
  --header 'Authorization: Bearer <YOUR_API_KEY>' 
  --header 'x-continuation: <continuation_token>' 
  --header 'Content-type: application/json'

Try the Kontent.ai APIs in Postman collection! Our Postman collection is regularly updated and contains endpoints for all Kontent.ai APIs.

We recommend that you fork the Kontent.ai APIs collection. Forking lets you stay up to date by pulling updates when needed.

Once you import the collection, you can start sending requests. Make sure to use environment variables for API keys.

Postman environments are sets of variables with specific values. You can use these variables everywhere in your requests in Postman.

For instance, the Kontent.ai APIs collection comes with an environment called Kontent.ai APIs sample values. The environment specifies a variable named environment_id, which is used in all requests. To get started quickly, we recommend you change the environment_id value to the ID of your own environment.

We offer the following SDKs to help you interact with Management API. However, you don't need an SDK to use the API.

• JavaScript/TypeScript SDK
• .NET SDK

The API key expiration length is set to 6 months by default. This is also the recommended expiration length.

When creating or regenerating your API keys, you can specify your preferred API key expiration length. The expiration length can vary from 1 minute to 2 years.

Before the API key expires, we'll send an email notification to the API key's owner.

• If the expiration date is less than a day apart from the API key's creation date, the email notification is sent immediately.
• If the expiration date is between 1–7 days apart form the API key's creation date, the email notification is sent 1 day before the expiration date.
• If the expiration date is more than a week apart from the API key's creation date, the email notification is sent 1 week before the expiration date.

The API key for Management API inherits the identity of the user who generates the key.

Any API operations performed with the key will show in the content item version history and audit log as changes made by the specific user.

The API key inherits the permissions of the user who creates it. For example, if you have the permissions to only manage API keys and manage taxonomy, the API key you create allows you to use Management API and work only with the taxonomy endpoints. Using such API key with any other endpoints will result in an 403 Unauthorized error.

The permission inheritance is dynamic. The API key permissions are directly tied to the current role of the user who creates it. If your role permissions change, the permissions of your API key change as well. No need to regenerate the API key.

If you regenerate your API key before its expiration date, the API key is revoked after a few minutes and you get a new API key. For requests made with a revoked API key, you receive the 403 Unauthorized error. You cannot revoke an API key without generating a new one.

The API key isn't revoked if you deactivate Management API for the project. Such API key remains valid and can be used again once Management API is activated for the project.

The scope of the API key is per project per user. When you create or regenerate an API key in one of the project's environments, this action applies to all of the project's environments.

This means you can use a single personal API key for all of your project's environments. For example, if you clone an environment using the API, you can use your current API key for the cloned environment.

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 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 API rate limits is per environment. Requests made with multiple API keys to a single environment count against a single rate limit.

These limits apply to requests made to a single environment.

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.

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.

For troubleshooting failed requests, the API provides error messages defined in a consumable format to help you identify and fix the issue.

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.

The state of the Management API may change in the future. However, the majority of the changes won't be breaking changes.

To create more robust scripts and integrations, we recommend you get familiar with the list of general changes to the API that aren't considered breaking. Make sure your app doesn't rely on a state that might change in the future. In general, the non-breaking changes include adding functionality or changes in the order of the returned data.

The following are NOT breaking changes:

• General:
  • Add a new endpoint.
  • Change the API behavior to fix a bug in the service.
  • Change the rate limitation.
  • Change error message text.
• Responses:
  • Add a new property to JSON objects.
  • Change the order of JSON object properties.
  • Add a new type of element for content types or snippets.
  • Add a new HTML element to rich text elements.
  • Add a new attribute to the HTML element in rich text elements.
  • Add a new value to the HTML element attribute in rich text elements.
  • Change the order of HTML element attributes in rich text elements.
  • Represent some characters as HTML entities.
  • Add a new response header.
  • Add a body to a request that contained none.
• Requests:
  • Add a new optional property to JSON objects.
  • Add a new optional attribute to the HTML element in rich text elements.
  • Add a new value to the HTML element attribute in rich text elements.
  • Add a new optional request header.
  • Add a new optional query string parameter.
  • Add an optional body to a request that contained none.

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.

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

Asset folders organize the assets in Kontent.ai just like folders in real life or folders on your devices.

With advanced asset management, you can customize images. Whenever you customize an image (by cropping it, for example), the customized version of the original image is saved as the image's rendition.

Rendition defines what image transformation parameters need to be applied to the original image to get the customized image.

Collections set boundaries for your content items. Check out use cases for collections and see how to set up collections.

To manage content items, send your 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.