Skip navigation

Management API v2

Download OpenAPI specification:Download

Introduction

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

Use the Management API v2 to manage the content, content model, and configuration of your project. 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.

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

The Management API accepts two kinds of API keys, the Management API key and the Subscription API key.

To get your Management API key, go to Kontent.ai > Project settings > API keys. To get your Subscription API key, go to Kontent.ai, click your initials on the bottom left, and click Subscriptions. Open a subscription and select Subscription API on the left.

  • Management API key
    • 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
    • Limited to subscription admins.
    • Provides access to the projects and subscriptions the 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 REST APIs, just like in the API references.

SDKs

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.

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