Skip navigation

Management API v2

Download OpenAPI specification:Download

The Management API is a secure REST API that provides read and write access to your Kontent projects and subscriptions.

Introduction

Use the API to import, update, or delete content in your Kontent project. When getting and updating content through the API, you always work with the latest versions of content, just like in the UI. The API cannot be used on published content unless you create new versions (in UI or via API) of the content items first.

Subscription admins on Enterprise plans with a Subscription API key can also use the Management API to manage users, roles, and projects under a subscription.

The base URL for all requests to the Management API is https://manage.kontent.ai/v2.

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/v2/projects/<YOUR_PROJECT_ID>/items \ --header 'Authorization: Bearer <YOUR_API_KEY>' \ --header 'x-continuation: <continuation_token>' \ --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.

Try the API with Postman

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

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

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.

You can authenticate Management API v2 requests using one of two types of keys:

  • Management API key, accepted by all project-specific endpoints (all endpoints except from Subscription).
  • Subscription API key, accepted by all endpoints.
Security Scheme TypeHTTP
HTTP Authorization Schemebearer
Bearer format"Bearer <YOUR_API_KEY>"

API keys

To get your API key for the Management API, go to Kontent > Project settings > API keys. The Management API accepts two kinds of API keys, Management API key and Subscription API key.

  • Subscription API key
    • Limited to subscription admins.
    • Provides access to the projects and subscriptions the admin has access to.
    • Can be used with all Management API endpoints.
  • Management API key
    • Limited to users with the Manage APIs permission.
    • Provides access to a single Kontent project. You will need a different Management API key for each of your projects.
    • Can be used with Management API endpoints that get or modify objects in a single project.

SDK

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

Guidelines on handling changes

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:

  • General:
    • Add a new endpoint.
    • Change the API behavior to fix a bug in the service.
    • Change 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 HTML element in rich text elements.
    • Add a new value to 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 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 request that contained none.

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.

message
required
string

The error message explaining what caused the error.

request_id
required
string Nullable

The performed request's unique ID.

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

The specific internal code for the type of error. Only useful for finding patterns among error requests.