Skip navigation

Subscription API

Download OpenAPI specification:Download

Introduction

Subscription API is a secure REST API that provides read and write access to users, roles, and projects under a Kontent.ai subscription. You need to be on Enterprise plans to use the API.

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

Authentication

To use Subscription API, send your requests over HTTPS and authenticate using the Authorization header in the following format: Authorization: Bearer <YOUR_SUBSCRIPTION_API_KEY>.

Bearer

Subscription 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_SUBSCRIPTION_API_KEY>"

API key

To get your Subscription API key:

  1. Go to Kontent.ai.
  2. Click your initials in the bottom left corner.
  3. Click Subscriptions.
  4. Select a subscription you want to manage.
  5. In Subscription API, click Copy to clipboard for the Subscription API key.

The Subscription API key is available only to subscription admins and provides:

  • Access to projects and users under a specific subscription.
  • Ability to use any of the 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 Subscription API. However, you don't need an SDK to use the API.

The SDKs for Subscription API are the same as for Management API.

API key scope and validity

By default, the Subscription API keys are valid for 4,000 days. The scope of the API keys isper user per subscription. This means you need a separate API key for each of your subscriptions.

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

API limitations

API requests limit

The requests made to Subscription 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 Subscription API within a specific time window.

There are per second and per minute time frames with different rate limits.

  • 10 requests per second
  • 400 requests per minute

Avoid parallel requests

We strongly advise against making multiple requests to the API in parallel. This 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, you can contact us with the response status and the request ID you get in the error response.

Subscription management

To use the subscription management endpoints for managing projects and users under a subscription, you need to:

Subscription project object

id
required
string <uuid>

The project container's internal ID.

name
required
string

The project's name.

is_active
required
boolean

A flag determining whether the project is active.

environments
required
Array of objects

The project's environments.

Copy
Expand all Collapse all
{
  • "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
  • "name": "Sample project",
  • "is_active": true,
  • "environments":
    [
    • {
      • "id": "c9bad3b5-2b91-4df9-9d4a-53d0bf14343b",
      • "name": "Production"
      },
    • {
      • "id": "fcd4e8cb-4577-4bd0-9104-07538b64eef7",
      • "name": "Dev"
      }
    ]
}

Subscription user object

id
required
string

The user's internal ID.

first_name
string

The user's first name.

last_name
string

The user's last name.

email
required
string <email>

The user's email address.

has_pending_invitation
required
boolean

A flag determining whether the user has any pending invitation to a project.

projects
required
Array of objects

The projects to which the user has been invited.

Copy
Expand all Collapse all
{
  • "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858",
  • "first_name": "John",
  • "last_name": "Doe",
  • "email": "jonh.doe@exmaple.com",
  • "has_pending_invitation": true,
  • "projects":
    [
    • {
      • "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
      • "name": "Sample project",
      • "environments":
        [
        • {
          }
        ]
      }
    ]
}

List projects under a subscription

get/{subscription_id}/projects
See full URL

Subscription API

https://manage.kontent.ai/v2/subscriptions/{subscription_id}/projects

Retrieve a dynamically paginated list of projects under the specified subscription.

This endpoint requires Enterprise plan and the Subscription API key.

Authorizations:
path Parameters
subscription_id
required
string

Identifies your subscription.

header Parameters
x-continuation
string

Determines the page of results to retrieve.

To get the next page of results, check the pagination object in the API response and set the x-continuation header parameter to the value of the continuation_token property.

Responses

200

A dynamically paginated list of projects in the subscription.

Request samples

Copy
// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Management;

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
});

var client = _fileSystemFixture.CreateMockClientWithResponse("SubscriptionUsers.json");

var response = await client.ListSubscriptionUsersAsync();

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "projects":
    [
    • {
      • "id": "a7d24131-b0c5-4dda-ad78-c0b409951493",
      • "name": "Sample project",
      • "is_active": true,
      • "environments":
        [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "pagination":
    {}
}

List users under a subscription

get/{subscription_id}/users
See full URL

Subscription API

https://manage.kontent.ai/v2/subscriptions/{subscription_id}/users

Retrieve a dynamically paginated list of users under the specified subscription. Includes the users' assignment to projects, environments, collections, roles, and languages.

This endpoint requires Enterprise plan and the Subscription API key.

Authorizations:
path Parameters
subscription_id
required
string

Identifies your subscription.

header Parameters
x-continuation
string

Determines the page of results to retrieve.

To get the next page of results, check the pagination object in the API response and set the x-continuation header parameter to the value of the continuation_token property.

Responses

200

A dynamically paginated list of users in the subscription.

Request samples

Copy
// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Management;

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
});

var response = await client.ListSubscriptionUsersAsync();

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "users":
    [
    • {
      • "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858",
      • "first_name": "John",
      • "last_name": "Doe",
      • "email": "jonh.doe@exmaple.com",
      • "has_pending_invitation": true,
      • "projects":
        [
        • {
          }
        ]
      }
    ],
  • "pagination":
    {}
}

Retrieve a user

get/{subscription_id}/users/{user_identifier}
See full URL

Subscription API

https://manage.kontent.ai/v2/subscriptions/{subscription_id}/users/{user_identifier}

Retrieve metadata about a specified user under the specified subscription. The metadata includes information about the user's access to projects and environments, and content in specific collections, roles, and languages.

This endpoint requires Enterprise plan and the Subscription API key.

Authorizations:
path Parameters
subscription_id
required
string

Identifies your subscription.

user_identifier
required
string

Identifies the user by their internal ID (e.g., mB9I0b-n-Zhe-x2my4NPjJovOiE0cqKgIyuVjqfKyW0) or email (e.g., email/user@example.com).

Responses

200

A single user object.

404

The specified user was not found.

Request samples

Copy
// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Management;

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "<YOUR_API_KEY>",
    ProjectId = "<YOUR_PROJECT_ID>"
});

var identifier = UserIdentifier.ByEmail("Joe.Joe@kontent.ai");
//var identifier = UserIdentifier.ById("usr_0vKjTCH2TkO687K3y3bKNS");

var response = await client.GetSubscriptionUserAsync(identifier);

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "e67eadda-dc58-4bf9-89fc-1dadc0b95858",
  • "first_name&