Skip navigation

Management API v2

Download OpenAPI specification:Download

Introduction

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

Use Management API v2 to manage your content, content model, and project settings.

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 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 Delivery REST API or Delivery GraphQL API.

Authentication

To use 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 requests to Management API by using either the Management API key or Subscription API key.

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

API keys

Management API accepts two kinds of API keys.

  • Management API key – Find it in Kontent.ai > Project settings > API keys.
    • Limited to users with the Manage APIs permission.
    • Provides access to a single Kontent.ai 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.
  • Subscription API key – Find it in Kontent.ai > Subscriptions > Your subscription > Subscription API.
    • Limited to subscription admins.
    • Provides access to the projects and subscriptions that the subscription admin has access to.
    • Can be used with all Management API endpoints.

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 APIs, just like in the API references.

SDKs

We offer the following SDKs to help you interact with Management 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.

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 o