Management API v2 (2)

Download OpenAPI specification:Download

Kontent.ai Support: support@kontent.ai License: MIT Terms of Service

About Management API

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 to manage your content & assets, content model, environment settings, and users.

Related paths

Making requests

To use Management API, ensure Management API is enabled for your environment, and use a valid personal API key.

  • To ensure Management API is enabled for your environment, go to Environment settings > General > Enabled APIs, and use the toggle to activate Management API.
  • To get a valid API key, go to Project settings > API keys > Management API keys, and click Create Management API key.

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'

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.

Postman collection

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

Import the Postman collection

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.

Use environment variables

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.

SDKs

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

Authentication

BearerAuthentication

Management API uses OAuth 2.0 bearer token (API key) to authorize requests. Send your requests over HTTPS and authenticate using the Authorization header in the following format: Authorization: Bearer <YOUR_API_KEY>. Requests with an incorrect or missing Authorization header will fail with an error.

You need to use a valid API key to make requests.

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "<YOUR_API_KEY>"

API keys

You can use two kinds of Management API keys:

  • Management API keys with a static set of customizable permissions. Use unique Management API keys when integrating with third-party services or for continuous usage in production.
  • Personal API keys with a dynamic set of inherited permissions. The API key has the same permissions as its owner. Use personal API keys in your personal projects for testing. Don’t share your personal API keys with anyone else.

Find more about how to manage your API keys.

Expiration

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.

Email reminders before the expiration

Before the API keys expire, the users who can manage the API keys are notified via email.

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

Identity

The Management API key is standalone and not tied to any individual user. API operations performed with the Management API key are shown in the content item version history and audit log as changes made by the specific API key.

The Personal API key inherits the identity of the user who generates the key. API operations performed with the personal API key are considered changes made by the specific user.

Permission

The personal API key dynamically inherits the permissions of the user who creates it. For example, if you have the Manage taxonomy permission, the personal API key grants access only to Management API endpoints for managing taxonomy groups. Using such an API key with other endpoints results in a 403 Unauthorized error. If your role permissions change, your personal API key's permissions also change.

The Management API key's permissions are customizable. You can tailor them to your specific apps and integrations. For example, you can configure a Management API key to grant read-only access to your content items.

Revocation

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.

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

Scope

For the Management API key, the scope is per project because it's not tied to any specific user. For Personal API keys, the scope is per project per user. The scope of each API key might also be limited to specific environments.

This means you can use a single API key for all 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.

API limitations

API requests limit

The requests made to Management API count towards the overall API calls limit set in the Fair Use Policy or your subscription plan.

There is no limit on the total number of API calls you can make.

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

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.

{
    "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 if your request is missing a required parameter or contains an invalid query parameter value.
401 Unauthorized The provided API key is doesn't provide access to the requested resource. The error can also occur if the API key is malformed or missing. Try copying and pasting your current API key to avoid typos.
403 Forbidden The provided API key is valid but doesn't provide permission for the specified resource.
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.

Array of objects

A list of specific issues that occurred when processing the request.

{
  • "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.

Guidelines on handling changes

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

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.

Adding assets is a 2-step process

  1. Upload a binary file to get a file reference to the file.
  2. Use the file reference to create a new asset that references the uploaded file.

Asset object

A single asset object.

Array of objects unique

The asset's descriptions for each active language.

Array of objects unique

An array of asset taxonomy elements as defined in the asset type.

The asset type can be managed only in the UI.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

external_id
string

The asset's external ID. The external ID can be specified when adding or upserting assets. Use this parameter as a unique identifier for your assets. If not specified, the external_id property is not present.

file_name
string

The file's name.

Determined by the file referenced in the file_reference property.

required
object

Points to a specific binary file uploaded to a Kontent.ai environment.

object

A reference to the folder containing the asset. You can specify a folder by its internal ID or external ID. Not present if the asset is not in a folder.

To return an asset to the top level outside any folders, use "id" : "00000000-0000-0000-0000-000000000000".

object

A reference to the collection that the asset is assigned to. You can specify a collection by its internal ID, codename, or external ID.

For projects created after the asset collections product release, the asset’s collection is set to the default collection unless specified when creating the asset. The collection property can be modified but cannot be set to null.

id
string <uuid>

The asset's internal ID.

codename
string

The asset's codename. Unless specified when adding or upserting assets, initially generated from the asset's title. If title is empty, the file_name is used.

image_height
integer or null <int32>

The image's height in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

image_width
integer or null <int32>

The image's width in pixels. Is null if the file is not an image.

Determined by the file referenced in the file_reference property.

last_modified
string <date-time>

ISO-8601 formatted date and time of the last change to the asset.

size
integer <int32>

The file's size in bytes.

Determined by the file referenced in the file_reference property.

title
string or null <= 200 characters

The asset's display name. The title can be specified when adding or upserting assets. Use title to better identify and filter your assets in the UI. If not specified, the title property is null.

type
string

The file's MIME type.

Determined by the file referenced in the file_reference property.

url
string

The asset's URL.

{
  • "descriptions": [
    • {
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000"
        },
      • "description": "The asset's alt text for the default language."
      }
    ],
  • "elements": [
    • {
      • "element": {
        • "id": "c7c3b834-2222-5677-89c4-b46f04489109"
        },
      • "value": [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "external_id": "custom-asset-identifier",
  • "file_name": "file_name.png",
  • "file_reference": {
    • "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
    • "type": "internal"
    },
  • "folder": {
    • "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea"
    },
  • "collection": {
    • "reference": {
      • "codename": "first_collection"
      }
    },
  • "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  • "codename": "my_asset",
  • "image_height": 548,
  • "image_width": 1280,
  • "last_modified": "2019-09-12T08:29:36.1645977Z",
  • "size": 148636,
  • "title": "Makes the asset easier to find when you need it",
  • "type": "image/png",
  • "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/806ec84e-7c71-4856-9519-ee3dd3558583/file_name.png"
}

Upload a binary file

post/projects/{environment_id}/files/{file_name}

Add a new file. The uploaded file will not be visible in the Kontent.ai UI unless you add an asset that uses the file.

Adding assets is a 2-step process

  1. Upload a binary file to get a file reference to the file.
  2. Use the file reference to create a new asset that references the uploaded file.

Maximum size limit for binary files is 100 MB.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
file_name
required
string [ 1 .. 500 ] characters

Specifies the name of the uploaded binary file. The file name specified in the URL will be used for the asset name when you create an asset.

If the name of your file contains reserved characters, you need to URL encode the file name first. For instance, use my%20file%232.png instead of my file#2.png. The file will then show as my file#2.png in the Kontent.ai UI.

Example: which-brewing-fits-you-1080px.jpg
header Parameters
Content-type
required
string

Specifies the media type of the binary data.

Example: image/jpeg
Content-length
required
integer <int32> >= 0

Specifies the size of the binary file in bytes.

Example: 125770
Request Body schema: application/octet-stream
required

The binary data of the file.

string <binary>
Responses
200

A file reference to the uploaded binary file.

400

The specified request body or the provided parameters are invalid.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
// Note that this approach works when using Node.js. See a worked example using the browser
import { ManagementClient } from '@kontent-ai/management-sdk';
import { readFileSync } from 'fs';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const data = readFileSync('which-brewing-fits-you-1080px.jpg');

const response = await client.uploadBinaryFile()
  .withData({
    binaryData: data,
    contentLength: data.byteLength,
    contentType: 'image/jpeg',
    filename: 'which-brewing-fits-you-1080px.jpg'
  })
  .toPromise();
Response samples
application/json
{
  • "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
  • "type": "internal"
}

Add an asset

post/projects/{environment_id}/assets

Use a file reference to link an existing binary file to a new asset. You can also create assets by upserting (PUT /assets/external-id/<external_id>).

Each binary file can be referenced only by a single asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

The asset to create.

Array of objects unique

The asset's descriptions for each active language.

Array of objects unique

An array of asset taxonomy elements as defined in the asset type.

The asset type can be managed only in the UI.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

external_id
string

The asset's external ID. The external ID can be specified when adding or upserting assets. Use this parameter as a unique identifier for your assets. If not specified, the external_id property is not present.

required
object

Points to a specific binary file uploaded to a Kontent.ai environment.

object

A reference to the folder containing the asset. You can specify a folder by its internal ID or external ID. Not present if the asset is not in a folder.

To return an asset to the top level outside any folders, use "id" : "00000000-0000-0000-0000-000000000000".

object

A reference to the collection that the asset is assigned to. You can specify a collection by its internal ID, codename, or external ID.

For projects created after the asset collections product release, the asset’s collection is set to the default collection unless specified when creating the asset. The collection property can be modified but cannot be set to null.

codename
string

The asset's codename. Unless specified when adding or upserting assets, initially generated from the asset's title. If title is empty, the file_name is used.

title
string or null <= 200 characters

The asset's display name. The title can be specified when adding or upserting assets. Use title to better identify and filter your assets in the UI. If not specified, the title property is null.

Responses
201

The created asset.

400

The specified request was invalid.

Request samples
application/json
{
  • "file_reference": {
    • "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    • "type": "internal"
    },
  • "title": "Description of what the file contains",
  • "folder": {
    • "external_id": "sacred-treasures"
    },
  • "collection": {
    • "reference": {
      • "codename": "first_collection"
      }
    },
  • "external_id": "custom-asset-identifier",
  • "descriptions": [
    • {
      • "language": {
        • "codename": "default"
        },
      • "description": "The asset's alt text in the default language describing what the file or image shows."
      }
    ],
  • "elements": [
    • {
      • "element": {
        • "codename": "taxonomy_categories"
        },
      • "value": [
        • {
          },
        • {
          }
        ]
      }
    ]
}
Response samples
application/json
{
  • "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  • "file_name": "file_name.jpeg",
  • "title": "Description of what the file contains",
  • "size": 148636,
  • "type": "image/jpeg",
  • "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/adf26cd2-1acb-403f-9d1e-6d04e46c39f1/file_name.png",
  • "image_width": 1280,
  • "image_height": 548,
  • "file_reference": {
    • "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    • "type": "internal"
    },
  • "folder": {
    • "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea"
    },
  • "descriptions": [
    • {
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000"
        },
      • "description": "The asset's alt text in the default language describing what the file or image shows."
      }
    ],
  • "elements": [
    • {
      • "element": {
        • "id": "c7c3b834-2222-5677-89c4-b46f04489109"
        },
      • "value": [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "external_id": "custom-asset-identifier",
  • "last_modified": "2017-09-12T08:29:36.1645977Z"
}

List assets

get/projects/{environment_id}/assets

Retrieve a dynamically paginated list of assets.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of assets.

400

The specified continuation token is incorrect.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listAssets()
  .toPromise();

// Gets all pages of results
// const response = await client.listAssets()
//   .toAllPromise();
Response samples
application/json
{
  • "assets": [
    • {
      • "descriptions": [
        • {
          }
        ],
      • "elements": [
        • {
          }
        ],
      • "external_id": "custom-asset-identifier",
      • "file_name": "file_name.png",
      • "file_reference": {
        • "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
        • "type": "internal"
        },
      • "folder": {
        • "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea"
        },
      • "collection": {
        • "reference": {
          }
        },
      • "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
      • "codename": "my_asset",
      • "image_height": 548,
      • "image_width": 1280,
      • "last_modified": "2019-09-12T08:29:36.1645977Z",
      • "size": 148636,
      • "title": "Makes the asset easier to find when you need it",
      • "type": "image/png",
      • "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/806ec84e-7c71-4856-9519-ee3dd3558583/file_name.png"
      }
    ],
  • "pagination": {}
}

Retrieve an asset

get/projects/{environment_id}/assets/{asset_identifier}

Retrieve information about a single asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
asset_identifier
required
string

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c
Responses
200

A single asset object with metadata about the asset and the referenced binary file.

404

The specified asset was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.viewAsset()
  .byAssetId('0270ea18-4842-4d09-9570-17b41bb37e2d')
  // .byAssetExternalId('which-brewing-fits-you')
  .toPromise();
Response samples
application/json
{
  • "descriptions": [
    • {
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000"
        },
      • "description": "The asset's alt text for the default language."
      }
    ],
  • "elements": [
    • {
      • "element": {
        • "id": "c7c3b834-2222-5677-89c4-b46f04489109"
        },
      • "value": [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "external_id": "custom-asset-identifier",
  • "file_name": "file_name.png",
  • "file_reference": {
    • "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
    • "type": "internal"
    },
  • "folder": {
    • "id": "8fe4ff47-0ca8-449d-bc63-c280efee44ea"
    },
  • "collection": {
    • "reference": {
      • "codename": "first_collection"
      }
    },
  • "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  • "codename": "my_asset",
  • "image_height": 548,
  • "image_width": 1280,
  • "last_modified": "2019-09-12T08:29:36.1645977Z",
  • "size": 148636,
  • "title": "Makes the asset easier to find when you need it",
  • "type": "image/png",
  • "url": "https://assets-us-01.kc-usercontent.com/8d20758c-d74c-4f59-ae04-ee928c0816b7/806ec84e-7c71-4856-9519-ee3dd3558583/file_name.png"
}

Upsert an asset

put/projects/{environment_id}/assets/{asset_identifier}

Update an existing asset, or add a new asset specified by external ID.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
asset_identifier
required
string

Identifies an asset by its internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c) or external ID (e.g., external-id/custom-identifier-of-your-asset).

  • When adding a new asset, use an external ID as the asset's identifier.
  • When updating an existing asset, identify the asset either by its internal ID or external ID.

New vs existing assets

If the specified external ID is not used by an existing asset, the API will create a new asset. For existing assets, the API updates only the specified asset's descriptions and title.

Example: external-id/custom-identifier-for-my-asset
Request Body schema: application/json
required

The asset to update or create.

Array of objects

Asset descriptions for each active language.

Array of objects unique

Asset taxonomy elements as defined in the asset type.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

object

A reference to the folder where you want to place the asset. To move the asset to the root outside any folders, use a reference {"id" : "00000000-0000-0000-0000-000000000000"}.

object

An object containing a reference to the collection containing the asset. You can specify a collection by its internal ID, codename, or external ID.

If you need to remove the asset from a collection, use a null reference {"reference": null}.

For projects created after the asset collections product release, the asset’s collection is set to the default collection unless specified when creating the asset. The collection property can be modified but cannot be set to null.

title
string [ 1 .. 200 ] characters

The title of the new asset. Use this parameter to better identify and filter your assets in the UI.

required
object

Points to a specific binary file uploaded to a Kontent.ai environment. This property is required only when creating an asset. If you update file_reference, the asset URL previously copied from the asset details may stop working.

codename
string

The asset's codename. Unless specified, initially generated from the asset's title. If title is empty, the file_name is used.

Responses
200

The specified asset was updated.

201

The specified asset was created.

400

The request body is invalid.

Request samples
application/json
{
  • "title": "Coffee Brewing Techniques",
  • "folder": {
    • "external_id": "another-folder"
    },
  • "collection": {
    • "reference": {
      • "codename": "first_collection"
      }
    },
  • "codename": "my_asset",
  • "descriptions": [
    • {
      • "language": {
        • "codename": "en-US"
        },
      • "description": "Coffee Brewing Techniques"
      },
    • {
      • "language": {
        • "codename": "es-ES"
        },
      • "description": "Técnicas para hacer café"
      }
    ],
  • "elements": [
    • {
      • "element": {
        • "codename": "taxonomy_categories"
        },
      • "value": [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "file_reference": {
    • "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    • "type": "internal"
    }
}
Response samples
application/json
{
  • "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
  • "folder": {
    • "id": "4033071a-5bc1-48da-8342-d129bb967d1d"
    },
  • "file_name": "which-brewing-fits-you-1080px.jpg",
  • "title": "Coffee Brewing Techniques",
  • "size": 125770,
  • "type": "image/jpeg",
  • "url": "https://assets-us-01.kc-usercontent.com/975bf280-fd91-488c-994c-2f04416e5ee3/fcbb12e6-66a3-4672-85d9-d502d16b8d9c/which-brewing-fits-you-1080px.jpg",
  • "image_width": 1000,
  • "image_height": 666,
  • "file_reference": {
    • "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
    • "type": "internal"
    },
  • "descriptions": [
    • {
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000"
        },
      • "description": "Coffee Brewing Techniques"
      },
    • {
      • "language": {
        • "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
        },
      • "description": "Técnicas para hacer café"
      }
    ],
  • "elements": [
    • {
      • "element": {
        • "id": "c7c3b834-2222-5677-89c4-b46f04489109"
        },
      • "value": [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "last_modified": "2017-09-12T08:29:36.1645977Z"
}

Delete an asset

delete/projects/{environment_id}/assets/{asset_identifier}

Delete an unused asset from an environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
asset_identifier
required
string

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c
Responses
204

The specified asset was deleted.

404

The specified asset was already deleted or doesn't exist.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteAsset()
  .byAssetId('1b458663-d23a-441c-8cc2-c2825fe53b48')
  // .byAssetExternalId('which-brewing-fits-you')
  .toPromise();
Response samples
application/json
{
  • "request_id": "00000000-0000-0000-6f12-0080000000c7",
  • "error_code": 105,
  • "message": "The requested asset 'fcbb12e6-66a3-4672-85d9-d502d16b8d9c' was not found."
}

Asset folders

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

Asset folders object

Defines all asset folders within a Kontent.ai environment.

required
Array of objects

All folders within a Kontent.ai environment.

last_modified
required
string <date-time>

ISO-8601 formatted date/time of the last change to the folder.

{
  • "folders": [
    • {
      • "id": "958001d8-2228-4373-b966-5262b5b96f71",
      • "name": "Downloads",
      • "external_id": "folder-with-downloadable-assets",
      • "folders": [
        • {
          }
        ]
      },
    • {
      • "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
      • "name": "Legal documents",
      • "external_id": "folder-documents",
      • "folders": [ ]
      }
    ],
  • "last_modified": "2019-08-08T08:16:24.3620957Z"
}

Retrieve asset folders

get/projects/{environment_id}/folders

Retrieve an array of all asset folders.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

All asset folders in the environment.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.listAssetFolders()
  .toPromise();
Response samples
application/json
{
  • "folders": [
    • {
      • "id": "958001d8-2228-4373-b966-5262b5b96f71",
      • "name": "Downloads",
      • "external_id": "folder-with-downloadable-assets",
      • "folders": [
        • {
          }
        ]
      },
    • {
      • "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
      • "name": "Legal documents",
      • "external_id": "folder-documents",
      • "folders": [ ]
      }
    ],
  • "last_modified": "2019-08-08T08:16:24.3620957Z"
}

Add asset folders

post/projects/{environment_id}/folders

Add one or more asset folders. If your environment already has folders, use modify asset folders instead.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json

The asset folders to add.

required
Array of objects

All folders within a Kontent.ai environment.

Array
external_id
string

The folder's external ID. Only present if specified via API when adding folders or modifying the folders array to add new folders.

folders
required
Array of objects

Any folders contained within the given folder.

name
required
string [ 1 .. 200 ] characters

The folder's name.

Responses
201

The created asset folders object.

400

The specified request body is invalid, or the environment already contains asset folders.

Request samples
application/json
{
  • "folders": [
    • {
      • "id": "958001d8-2228-4373-b966-5262b5b96f71",
      • "name": "Downloads",
      • "external_id": "folder-with-downloadable-assets",
      • "folders": [
        • {
          }
        ]
      },
    • {
      • "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
      • "name": "Legal documents",
      • "external_id": "folder-documents",
      • "folders": [ ]
      }
    ]
}
Response samples
application/json
{
  • "folders": [
    • {
      • "id": "958001d8-2228-4373-b966-5262b5b96f71",
      • "name": "Downloads",
      • "external_id": "folder-with-downloadable-assets",
      • "folders": [
        • {
          }
        ]
      },
    • {
      • "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
      • "name": "Legal documents",
      • "external_id": "folder-documents",
      • "folders": [ ]
      }
    ],
  • "last_modified": "2019-08-08T08:16:24.3620957Z"
}

Modify asset folders

patch/projects/{environment_id}/folders

Add, rename, or remove asset folders.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

The operations you want to perform on the folders.

Array
op
required
string

Specifies the operation to perform.

  • addInto to add new folders
  • remove to delete folders
  • rename to rename folders
object

Reference to an existing folder under which you want to add new folders.

required
object

The folder you want to add.

object

Reference to the existing folder after which you want to add the new folder.

Note: The before and after properties are mutually exclusive.

object

Reference to the existing folder before which you want to add the new folder.

Note: The before and after properties are mutually exclusive.

Responses
200

The modified asset folders.

400

The specified request body is invalid.

Request samples
application/json
[
  • {
    • "op": "addInto",
    • "value": {
      • "external_id": "folder-with-shared-assets",
      • "name": "Shared assets",
      • "folders": [ ]
      },
    • "before": {
      • "external_id": "folder-with-downloadable-assets"
      }
    },
  • {
    • "op": "remove",
    • "reference": {
      • "external_id": "folder-with-archived-assets"
      }
    },
  • {
    • "op": "rename",
    • "value": "Legal documents",
    • "reference": {
      • "external_id": "folder-documents"
      }
    }
]
Response samples
application/json
{
  • "folders": [
    • {
      • "id": "59aaaa55-1049-44bc-8785-0e327b271453",
      • "name": "Shared assets",
      • "external_id": "folder-with-shared-assets",
      • "folders": [ ]
      },
    • {
      • "id": "958001d8-2228-4373-b966-5262b5b96f71",
      • "name": "Downloads",
      • "external_id": "folder-with-downloadable-assets",
      • "folders": [
        • {
          }
        ]
      },
    • {
      • "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
      • "name": "Legal documents",
      • "external_id": "folder-documents",
      • "folders": [ ]
      }
    ],
  • "last_modified": "2022-03-27T13:21:11.38Z"
}

Asset renditions

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.

This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

Rendition object

rendition_id
string <uuid>

The rendition's ID.

asset_id
string <uuid>

The id of the asset this rendition belongs to.

external_id
string or null

The rendition's external ID. The external ID can be specified when adding renditions. If not specified, the external_id property is not present.

required
object

Specifies how to transform the original image asset.

The image area to use for the transformation is determined by the x, y, width, and height properties. The custom_width and custom_height properties set the dimensions of the output image.

The x and y coordinates define a point in the original image. The point is specified as the distance from the top-left corner of the original image asset in pixels. The whole area must be within the borders of the original image. Upscaling, that is setting the custom_width and custom_height greater than width and height, is not allowed.

last_modified
string <date-time>

ISO-8601 formatted date/time of the last change to the rendition.

{
  • "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
  • "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
  • "external_id": "rendition-external-id-01",
  • "transformation": {
    • "mode": "rect",
    • "fit": "clip",
    • "custom_width": 250,
    • "custom_height": 50,
    • "x": 0,
    • "y": 30,
    • "width": 500,
    • "height": 100
    },
  • "last_modified": "2022-03-01T10:54:52.1001012Z"
}

List renditions

get/projects/{environment_id}/assets/{asset_identifier}/renditions

Returns a paginated list of all renditions of the specified asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
asset_identifier
required
string

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of asset renditions.

400

The specified continuation token is incorrect.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listAssetRenditions()
  .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c')
  // .byAssetExternalId('which-brewing-fits-you')
  .toPromise();
Response samples
application/json
{
  • "asset_renditions": [
    • {
      • "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
      • "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
      • "external_id": "rendition-external-id-01",
      • "transformation": {
        • "mode": "rect",
        • "fit": "clip",
        • "custom_width": 250,
        • "custom_height": 50,
        • "x": 0,
        • "y": 30,
        • "width": 500,
        • "height": 100
        },
      • "last_modified": "2022-03-01T10:54:52.1001012Z"
      }
    ],
  • "pagination": {}
}

Add a rendition

post/projects/{environment_id}/assets/{asset_identifier}/renditions

Creates a new rendition of the specified asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
asset_identifier
required
string

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c
Request Body schema: application/json
required

Specify how to transform the original asset.

external_id
string or null

The rendition's external ID. The external ID can be specified when adding renditions. If not specified, the external_id property is not present.

required
object

Specifies how to transform the original image asset.

The image area to use for the transformation is determined by the x, y, width, and height properties. The custom_width and custom_height properties set the dimensions of the output image.

The x and y coordinates define a point in the original image. The point is specified as the distance from the top-left corner of the original image asset in pixels. The whole area must be within the borders of the original image. Upscaling, that is setting the custom_width and custom_height greater than width and height, is not allowed.

Responses
201

The newly created rendition.

400

The specified request body is invalid.

Request samples
application/json
{
  • "transformation": {
    • "mode": "rect",
    • "fit": "clip",
    • "custom_width": 250,
    • "custom_height": 50,
    • "x": 0,
    • "y": 30,
    • "width": 500,
    • "height": 100
    },
  • "external_id": "hero-image-rendition"
}
Response samples
application/json
{
  • "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
  • "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
  • "external_id": "rendition-external-id-01",
  • "transformation": {
    • "mode": "rect",
    • "fit": "clip",
    • "custom_width": 250,
    • "custom_height": 50,
    • "x": 0,
    • "y": 30,
    • "width": 500,
    • "height": 100
    },
  • "last_modified": "2022-03-01T10:54:52.1001012Z"
}

Retrieve a rendition

get/projects/{environment_id}/assets/{asset_identifier}/renditions/{rendition_identifier}

Retrieve a rendition of the specified asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
asset_identifier
required
string

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c
rendition_identifier
required
string

Identifies a rendition by its internal ID (e.g., ce559491-0fc1-494b-96f3-244bc095de57) or external ID (e.g., external-id/hero-image-rendition).

Example: ce559491-0fc1-494b-96f3-244bc095de57
Responses
200

A single asset rendition object.

404

The specified asset rendition was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.viewAssetRendition()
  .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c')
  // .byAssetExternalId('which-brewing-fits-you')
  .byRenditionId('ce559491-0fc1-494b-96f3-244bc095de57')
  // .byRenditionExternalId('hero-image-rendition')
  .toPromise();
Response samples
application/json
{
  • "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
  • "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
  • "external_id": "rendition-external-id-01",
  • "transformation": {
    • "mode": "rect",
    • "fit": "clip",
    • "custom_width": 250,
    • "custom_height": 50,
    • "x": 0,
    • "y": 30,
    • "width": 500,
    • "height": 100
    },
  • "last_modified": "2022-03-01T10:54:52.1001012Z"
}

Modify a rendition

put/projects/{environment_id}/assets/{asset_identifier}/renditions/{rendition_identifier}

Modify a rendition of the asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
asset_identifier
required
string

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c
rendition_identifier
required
string

Identifies a rendition by its internal ID (e.g., ce559491-0fc1-494b-96f3-244bc095de57) or external ID (e.g., external-id/hero-image-rendition).

Example: ce559491-0fc1-494b-96f3-244bc095de57
Request Body schema: application/json
required
object

Specifies how to transform the original image asset.

The image area to use for the transformation is determined by the x, y, width, and height properties. The custom_width and custom_height properties set the dimensions of the output image.

The x and y coordinates define a point in the original image. The point is specified as the distance from the top-left corner of the original image asset in pixels. The whole area must be within the borders of the original image. Upscaling, that is setting the custom_width and custom_height greater than width and height, is not allowed.

mode
required
string

The transformation's mode. Only the rect mode is allowed.

The rect mode selects a sub-region of the original image to use for processing.

fit
required
string

Controls how the output image is constrained within the provided width and height boundaries after resizing. Only the clip resize fit mode is allowed.

custom_width
required
integer <int32> >= 0

The output image's width in pixels. Must be smaller than width.

Use custom_width if you want to resize the rectangle region selected via x, y, width, and height. That is to keep the contents of the selected rectangle region but make the output image smaller.

custom_height
required
integer <int32> >= 0

The output image's height in pixels. Must be smaller than height.

Use custom_height if you want to resize the rectangle region selected via x, y, width, and height. That is to keep the contents of the selected rectangle region but make the output image smaller.

x
required
integer <int32> >= 0

Represents a position on the horizontal axis of the original image as the distance from the image's top-left corner in pixels. Combined with the y property, the coordinates specify the top-left corner of the source rectangle region defined by width and height.

The x's maximum value depends on the width parameter. The whole rectangle must fit within the borders of the original image.

y
required
integer <int32> >= 0

Represents a position on the vertical axis of the original image as the distance from the image's top-left corner in pixels. Combined with the x property, the coordinates specify the top-left corner of the source rectangle region defined by width and height.

The y's maximum value depends on the height parameter. The whole rectangle must fit within the borders of the original image.

width
required
integer

Starting at the coordinates defined by x and y, specifies the width of the rectangle area.

height
required
integer

Starting at the coordinates defined by x and y, specifies the height of the rectangle area.

Responses
200

The updated rendition.

400

The specified request body is invalid.

Request samples
application/json
{
  • "transformation": {
    • "mode": "rect",
    • "fit": "clip",
    • "custom_width": 250,
    • "custom_height": 50,
    • "x": 0,
    • "y": 30,
    • "width": 500,
    • "height": 100
    }
}
Response samples
application/json
{
  • "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
  • "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
  • "external_id": "rendition-external-id-01",
  • "transformation": {
    • "mode": "rect",
    • "fit": "clip",
    • "custom_width": 250,
    • "custom_height": 50,
    • "x": 0,
    • "y": 30,
    • "width": 500,
    • "height": 100
    },
  • "last_modified": "2022-03-01T10:54:52.1001012Z"
}

Collections

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

Collection object

id
string

The collection's internal ID.

name
required
string [ 1 .. 200 ] characters

The collection's name.

codename
string [ 1 .. 210 ] characters

The collection's codename. Unless set while creating the collection, it is initially generated from the collection's name.

external_id
string

The collection's external ID.

Only present if defined when adding a new collection via API.

{
  • "id": "af678509-1c20-5c9e-868c-b84146000a2d",
  • "name": "US branch",
  • "codename": "us_branch",
  • "external_id": "my-collection-id"
}

List collections

get/projects/{environment_id}/collections

Retrieve an array of all collections.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

All collections in the environment.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var response = await client.ListCollectionsAsync();
Response samples
application/json
{
  • "collections": [
    • {
      • "id": "00000000-0000-0000-0000-000000000000",
      • "name": "Default",
      • "codename": "default"
      },
    • {
      • "id": "56ddd0f8-d3a3-5e36-9ccb-80dbe77aed23",
      • "external_id": "second_external_id",
      • "name": "Second collection",
      • "codename": "second_collection"
      }
    ],
  • "last_modified": "2021-03-04T08:16:24.3620957Z"
}

Modify collections

patch/projects/{environment_id}/collections

Add, reorder, update, or remove collections.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

The operations you want to perform on the collections.

Array
op
required
string

Specifies the operation to perform.

  • addInto to add new collections
  • move to change collections' order
  • remove to delete collections
  • replace to update collections (e.g., change collection's name)
required
object

The collection you want to add.

object

Reference to the existing collection after which you want to add the new collection.

Note: The before and after properties are mutually exclusive.

object

Reference to the existing collection before which you want to add the new collection.

Note: The before and after properties are mutually exclusive.

Responses
200

The modified collections in the environment.

400

The specified request body is invalid.

Request samples
application/json
[
  • {
    • "op": "addInto",
    • "value": {
      • "external_id": "another-collection",
      • "name": "Another collection",
      • "codename": "another_collection_codename"
      },
    • "after": {
      • "codename": "second_collection"
      }
    },
  • {
    • "op": "move",
    • "reference": {
      • "codename": "important_collection"
      },
    • "before": {
      • "codename": "first_collection"
      }
    },
  • {
    • "op": "remove",
    • "reference": {
      • "codename": "extra_collection"
      }
    },
  • {
    • "op": "replace",
    • "property_name": "name",
    • "value": "A new name",
    • "reference": {
      • "codename": "second_collection"
      }
    }
]
Response samples
application/json
{
  • "collections": [
    • {
      • "id": "00000000-0000-0000-0000-000000000000",
      • "name": "Default",
      • "codename": "default"
      },
    • {
      • "id": "56ddd0f8-d3a3-5e36-9ccb-80dbe77aed23",
      • "external_id": "second_external_id",
      • "name": "Second collection",
      • "codename": "second_collection"
      }
    ],
  • "last_modified": "2021-03-04T08:16:24.3620957Z"
}

Content items

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.

Content item object

The content item object contains metadata about your content, such as the name of the content item and when the item was last modified. It doesn't contain any content directly.

Content items serve as wrappers for language variants. Language variants hold the items' content even in environments with just one language. Content items have as many variants as there are active languages in your environment.

id
string <uuid>

The content item's internal ID.

name
required
string [ 1 .. 200 ] characters

The content item's display name.

codename
string [ 1 .. 60 ] characters

The content item's codename. Unless set while creating the content item, it is initially generated from the item's name and can later be modified.

required
object

Reference to the item's content type.

object

Reference to the item's collection. Unless set while creating the content item, the property references the default collection and can later be modified.

The default collection will always have the ID of 00000000-0000-0000-0000-000000000000.

Array of objects >= 0 items

A list of references to the spaces the item belongs to. This is based on the item's collection and the spaces that the collection is assigned to.

Array of objects unique
Deprecated

The content item's location (or locations) in the sitemap.

external_id
string

The content item's external ID. The external ID can be used as a unique identifier to retrieve content from a different system.

External IDs cannot be upserted into exisiting items.

last_modified
string <date-time>

The ISO-8601 formatted date and time of the last change to the content item.

Moving content items through workflow doesn't affect the last_modified value.

{
  • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
  • "name": "My article",
  • "codename": "my_article",
  • "type": {
    • "id": "d89b6348-7cdc-444a-8e1e-adacb564f2a2"
    },
  • "collection": {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "spaces": [
    • {
      • "id": "dcbf90fb-7135-4465-8102-b3e739821ed8"
      },
    • {
      • "id": "39efe8a4-23d2-4d3a-8dfb-07789668474f"
      }
    ],
  • "sitemap_locations": [ ],
  • "external_id": "custom-identifier-for-my-article",
  • "last_modified": "2023-04-04T13:45:30.7692802Z"
}

Add a content item

post/projects/{environment_id}/items

Create a new content item based on a specific content type.

Content items don't contain any content themselves directly. They serve as wrappers for language variants. Language variants hold the items' content even in environments with a single language.

To change the content in content items, upsert their specific language variant.

If you need to import content from another system and maintain your existing identifiers, specify your custom identifiers as the content item's external ID using the external_id property.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

The content item to be added.

name
required
string [ 1 .. 200 ] characters

The content item's display name.

codename
string [ 1 .. 60 ] characters

The content item's codename. Unless set while creating the content item, it is initially generated from the item's name and can later be modified.

required
object

Reference to the item's content type.

object

Reference to the item's collection. Unless set while creating the content item, the property references the default collection and can later be modified.

The default collection will always have the ID of 00000000-0000-0000-0000-000000000000.

Array of objects unique
Deprecated

The content item's location (or locations) in the sitemap.

external_id
string

The content item's external ID. The external ID can be used as a unique identifier to retrieve content from a different system.

External IDs cannot be upserted into exisiting items.

Responses
201

The content item was created.

400

The specified request body is invalid or the item already exists.

Request samples
application/json
{
  • "name": "My article",
  • "codename": "my_article_2",
  • "type": {
    • "codename": "article"
    },
  • "collection": {
    • "id": "1b9705bf-cea7-45bb-a0f0-4451495b8cce"
    },
  • "external_id": "custom-item-identifier"
}
Response samples
application/json
{
  • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
  • "name": "My article",
  • "codename": "my_article_2",
  • "type": {
    • "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
    },
  • "collection": {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "sitemap_locations": [ ],
  • "external_id": "custom-item-identifier",
  • "last_modified": "2020-04-04T13:45:30.7692802Z"
}

List content items

get/projects/{environment_id}/items

Retrieve a dynamically paginated list of content items.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of content items.

400

The specified continuation token is incorrect.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listContentItems()
  .toPromise();

// Gets all pages of results
// const response = await client.listContentItems()
//   .toAllPromise();
Response samples
application/json
{
  • "items": [
    • {
      • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
      • "name": "My article",
      • "codename": "my_article",
      • "type": {
        • "id": "d89b6348-7cdc-444a-8e1e-adacb564f2a2"
        },
      • "collection": {
        • "id": "00000000-0000-0000-0000-000000000000"
        },
      • "spaces": [
        • {
          },
        • {
          }
        ],
      • "sitemap_locations": [ ],
      • "external_id": "custom-identifier-for-my-article",
      • "last_modified": "2023-04-04T13:45:30.7692802Z"
      }
    ],
  • "pagination": {}
}

Retrieve a content item

get/projects/{environment_id}/items/{item_identifier}

Retrieve metadata about a content item.

If you want to retrieve content data, see how to retrieve language variants of a content item.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
Responses
200

The specified content item.

404

The specified content item was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.viewContentItem()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .toPromise();
Response samples
application/json
{
  • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
  • "name": "My article",
  • "codename": "my_article",
  • "type": {
    • "id": "d89b6348-7cdc-444a-8e1e-adacb564f2a2"
    },
  • "collection": {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "spaces": [
    • {
      • "id": "dcbf90fb-7135-4465-8102-b3e739821ed8"
      },
    • {
      • "id": "39efe8a4-23d2-4d3a-8dfb-07789668474f"
      }
    ],
  • "sitemap_locations": [ ],
  • "external_id": "custom-identifier-for-my-article",
  • "last_modified": "2023-04-04T13:45:30.7692802Z"
}

Upsert a content item

put/projects/{environment_id}/items/{item_identifier}

Update or create a content item.

  • To update a content item, you need to identify the existing item by its internal ID, external ID, or codename.
  • To create a content item, you need to specify the external ID as the item's identifier. You can also specify external ID when adding content items.

Content items don't contain any content themselves directly. They serve as wrappers for language variants. Language variants hold the items' content even in environments with a single language.

To change the content in content items, upsert their specific language variant.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

External IDs

If the provided external ID is not used by an existing content item, the API will try to create a new item.

If the content item specified by the external ID already exists, the properties specified in the request body will be updated.

Example: external-id/custom-identifier-for-my-article
Request Body schema: application/json
required

The content item to update or create.

Any of:

The content item to update.

name
required
string [ 1 .. 200 ] characters

The content item's display name.

codename
string

The content item's codename. Unless set while creating the content item, it is initially generated from the item's name and can later be modified. When only updating the name property, the item's codename is not affected by this change.

object

Reference to the item's collection. Unless set while creating the content item, the property references the default collection and can later be modified.

The default collection will always have the ID of 00000000-0000-0000-0000-000000000000.

Array of objects
Deprecated

One or more references to sitemap locations.

Responses
200

The updated content item.

201

The specified content item was created.

400

The specified request body is invalid.

Request samples
application/json
{
  • "name": "My new article",
  • "codename": "my_article",
  • "collection": {
    • "id": "00000000-0000-0000-0000-000000000000",
    • "codename": "default"
    },
  • "sitemap_locations": [ ]
}
Response samples
application/json
{
  • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
  • "name": "My new article",
  • "codename": "my_article",
  • "type": {
    • "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
    },
  • "collection": {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "sitemap_locations": [ ],
  • "last_modified": "2020-04-04T13:45:30.7692802Z"
}

Delete a content item

delete/projects/{environment_id}/items/{item_identifier}

Delete a content item.

If you only want to delete a specific language variant, see how to delete a language variant.

When you delete the last variant of a content item, the whole content item is deleted.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
Responses
204

The specified content item was deleted from the environment.

404

The specified content item was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteContentItem()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59714')
  .toPromise();
Response samples
application/json
{
  • "request_id": "2d2803b7-9b67-4bd8-b3d2-436aa077827f",
  • "error_code": 100,
  • "message": "The requested content item 'f4b3fc05-e988-4dae-9ac1-a94aba566474' was not found."
}

Content types

Content type object

Content types specify the structure of your content using elements. This structure is then applied to your content items and components. For an improved authoring experience, we recommend you put the elements in content groups.

id
string <uuid>

The content type's internal ID.

codename
string [ 1 .. 60 ] characters

The content type's codename. Unless set while creating the content type, it is initially generated from the type's name and can later be modified.

external_id
string

The content type's external ID. Only present if defined when creating the content type via API.

last_modified
string <date-time>

ISO-8601 formatted date and time of the last change to the content type.

name
required
string [ 1 .. 50 ] characters

The content type's display name.

Array of objects

The content type's content groups. If the content type doesn't have any content groups, the content_groups array is empty.

required
Array of Asset type element (object) or Content type snippet element (object) or Custom type element (object) or Date & time type element (object) or Guidelines type element (object) or Linked items type element (object) or Multiple choice type element (object) or Number type element (object) or Rich text type element (object) or SubpagesTypeElement (object) or TaxonomyTypeElement (object) or TextTypeElement (object) or UrlSlugTypeElement (object) >= 0 items unique

Elements within the content type. The order of the content type elements might not match their order in the UI.

{
  • "id": "dd1439d5-4ee2-4895-a4e4-5b0d9d8c754e",
  • "codename": "new_article",
  • "external_id": "custom-content-type-id",
  • "last_modified": "2021-06-17T06:28:11.6503569Z",
  • "name": "Article",
  • "content_groups": [
    • {
      • "id": "00000000-0000-0000-0000-000000000000",
      • "name": "Content",
      • "codename": "content"
      },
    • {
      • "id": "0acae5f5-5479-46e9-aad0-9481abb4dcab",
      • "name": "Author",
      • "codename": "author"
      },
    • {
      • "id": "b619a436-4e27-4cf3-8e42-c54ad9fccef7",
      • "name": "URL",
      • "codename": "url"
      }
    ],
  • "elements": [
    • {
      • "snippet": {
        • "id": "b14f8a4a-229d-4429-9474-4d6b9789cb95"
        },
      • "type": "snippet",
      • "id": "4e8b4583-f4f9-4db8-b9e5-683a9ed8cac6",
      • "codename": "snippet_with_title_element",
      • "is_non_localizable": false,
      • "content_group": {
        • "id": "00000000-0000-0000-0000-000000000000"
        }
      },
    • {
      • "maximum_text_length": null,
      • "maximum_image_size": null,
      • "allowed_content_types": [
        • {
          }
        ],
      • "allowed_item_link_types": [ ],
      • "image_width_limit": null,
      • "image_height_limit": null,
      • "allowed_image_types": "any",
      • "allowed_blocks": [
        • "text",
        • "tables",
        • "components-and-items"
        ],
      • "allowed_formatting": [ ],
      • "allowed_text_blocks": [
        • "paragraph",
        • "heading-two",
        • "heading-three",
        • "heading-four",
        • "ordered-list",
        • "unordered-list"
        ],
      • "allowed_table_blocks": [
        • "text"
        ],
      • "allowed_table_formatting": [ ],
      • "allowed_table_text_blocks": [
        • "paragraph"
        ],
      • "name": "Content",
      • "guidelines": "Make it snappy.",
      • "is_required": true,
      • "is_non_localizable": false,
      • "type": "rich_text",
      • "id": "23375e4a-2ed8-42bf-aa3a-dfb32e6a42ec",
      • "codename": "content",
      • "content_group": {
        • "id": "00000000-0000-0000-0000-000000000000"
        }
      },
    • {
      • "item_count_limit": {
        • "value": 1,
        • "condition": "at_least"
        },
      • "allowed_content_types": [
        • {
          }
        ],
      • "name": "Author",
      • "guidelines": "Select the author or authors.",
      • "is_required": true,
      • "is_non_localizable": false,
      • "type": "modular_content",
      • "id": "02249cf0-e9db-4e96-a582-479a2650fbc1",
      • "codename": "author",
      • "content_group": {
        • "id": "0acae5f5-5479-46e9-aad0-9481abb4dcab"
        }
      },
    • {
      • "depends_on": {
        • "snippet": {
          },
        • "element": {
          }
        },
      • "name": "URL",
      • "guidelines": "If needed, provide a custom URL slug.",
      • "is_required": true,
      • "is_non_localizable": false,
      • "type": "url_slug",
      • "id": "4a90f541-2de4-4a69-b1ef-fe53c6abf0f4",
      • "codename": "url",
      • "content_group": {
        • "id": "b619a436-4e27-4cf3-8e42-c54ad9fccef7"
        }
      }
    ]
}

Content group object

Every element in a content type can be assigned to a single content group. If you define one or more content groups for a content type, every element in the type must be assigned to a content group.

id
string <uuid>

The content group's internal ID.

name
required
string [ 1 .. 50 ] characters

The content group's display name.

codename
string [ 1 .. 60 ] characters

The content group's codename. Unless specified, initially generated from the group's name.

When adding a content type, you must identify the content group by specifying its codename, external ID, or both. In the content elements, you specify a reference to the content group using either the group's codename or external ID.

external_id
string

The content group's external ID.

When adding a content type, you must identify the content group by specifying its codename, external ID, or both. In the content elements, you specify a reference to the content group using either the group's codename or external ID.

{
  • "id": "325107f6-5dfb-21a1-b24e-fa13be1fef1c",
  • "name": "My first group",
  • "codename": "my_first_group",
  • "external_id": "first-group"
}

Add a content type

post/projects/{environment_id}/types

Create a new content type.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

The content type to be added.

codename
string [ 1 .. 60 ] characters

The content type's codename. Unless set while creating the content type, it is initially generated from the type's name and can later be modified.

external_id
string

The content type's external ID. Only present if defined when creating the content type via API.

name
required
string [ 1 .. 50 ] characters

The content type's display name.

Array of objects

The content type's content groups. If the content type doesn't have any content groups, the content_groups array is empty.

required
Array of Asset type element (object) or Content type snippet element (object) or Custom type element (object) or Date & time type element (object) or Guidelines type element (object) or Linked items type element (object) or Multiple choice type element (object) or Number type element (object) or Rich text type element (object) or SubpagesTypeElement (object) or TaxonomyTypeElement (object) or TextTypeElement (object) or UrlSlugTypeElement (object) >= 0 items unique

Elements within the content type. The order of the content type elements might not match their order in the UI.

Responses
201

The created content type.

400

The specified request body is invalid.

Request samples
application/json
{
  • "external_id": "article",
  • "name": "Article",
  • "codename": "my_article",
  • "content_groups": [
    • {
      • "name": "Article copy",
      • "external_id": "article-copy"
      },
    • {
      • "name": "Author",
      • "codename": "author"
      }
    ],
  • "elements": [
    • {
      • "name": "Article title",
      • "codename": "title",
      • "type": "text",
      • "content_group": {
        • "external_id": "article-copy"
        }
      },
    • {
      • "name": "Article body",
      • "codename": "body",
      • "type": "rich_text",
      • "content_group": {
        • "external_id": "article-copy"
        }
      },
    • {
      • "name": "Author bio",
      • "codename": "bio",
      • "allowed_blocks": [
        • "images",
        • "text"
        ],
      • "type": "rich_text",
      • "content_group": {
        • "codename": "author"
        }
      }
    ]
}
Response samples
application/json
{
  • "id": "d622fc28-5202-511a-9dbf-a3ee363b6c7c",
  • "codename": "my_article",
  • "last_modified": "2019-08-26T08:38:49.7302435Z",
  • "external_id": "article",
  • "name": "Article",
  • "content_groups": [
    • {
      • "id": "c2deb028-1bad-5191-952f-ace4b256ba61",
      • "name": "Article copy",
      • "codename": "article_copy",
      • "external_id": "article-copy"
      },
    • {
      • "id": "46d8c4db-df5c-55ab-887a-458f7ad063a1",
      • "name": "Author",
      • "codename": "author"
      }
    ],
  • "elements": [
    • {
      • "maximum_text_length": null,
      • "name": "Article title",
      • "guidelines": null,
      • "is_required": false,
      • "is_non_localizable": false,
      • "type": "text",
      • "id": "e32743cd-7616-4a4a-9948-c9fcb54bff3f",
      • "codename": "title",
      • "content_group": {
        • "id": "c2deb028-1bad-5191-952f-ace4b256ba61"
        }
      },
    • {
      • "maximum_text_length": null,
      • "maximum_image_size": null,
      • "allowed_content_types": [ ],
      • "allowed_item_link_types": [ ],
      • "image_width_limit": null,
      • "image_height_limit": null,
      • "allowed_image_types": "any",
      • "allowed_blocks": [ ],
      • "allowed_text_blocks": [ ],
      • "allowed_formatting": [ ],
      • "allowed_table_blocks": [ ],
      • "allowed_table_text_blocks": [ ],
      • "allowed_table_formatting": [ ],
      • "name": "Article body",
      • "guidelines": null,
      • "is_required": false,
      • "is_non_localizable": false,
      • "type": "rich_text",
      • "id": "bbddb422-774c-4226-984d-c15656df6108",
      • "codename": "body",
      • "content_group": {
        • "id": "c2deb028-1bad-5191-952f-ace4b256ba61"
        }
      },
    • {
      • "maximum_text_length": null,
      • "maximum_image_size": null,
      • "allowed_content_types": [ ],
      • "allowed_item_link_types": [ ],
      • "image_width_limit": null,
      • "image_height_limit": null,
      • "allowed_image_types": "any",
      • "allowed_blocks": [
        • "images",
        • "text"
        ],
      • "allowed_text_blocks": [ ],
      • "allowed_formatting": [ ],
      • "allowed_table_blocks": [ ],
      • "allowed_table_text_blocks": [ ],
      • "allowed_table_formatting": [ ],
      • "name": "Author bio",
      • "guidelines": null,
      • "is_required": false,
      • "is_non_localizable": false,
      • "type": "rich_text",
      • "id": "1c795ec7-368c-4c22-830e-e8b969f596be",
      • "codename": "bio",
      • "content_group": {
        • "id": "46d8c4db-df5c-55ab-887a-458f7ad063a1"
        }
      }
    ]
}

List content types

get/projects/{environment_id}/types

Retrieve a dynamically paginated list of content types.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of content types.

400

The specified continuation token is incorrect.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listContentTypes()
  .toPromise();

// Gets all pages of results
// const response = await client.listContentTypes()
//   .toAllPromise();
Response samples
application/json
{
  • "types": [
    • {
      • "id": "dd1439d5-4ee2-4895-a4e4-5b0d9d8c754e",
      • "codename": "new_article",
      • "external_id": "custom-content-type-id",
      • "last_modified": "2021-06-17T06:28:11.6503569Z",
      • "name": "Article",
      • "content_groups": [
        • {
          },
        • {
          },
        • {
          }
        ],
      • "elements": [
        • {
          },
        • {
          },
        • {
          },
        • {
          }
        ]
      }
    ],
  • "pagination": {}
}

Retrieve a content type

get/projects/{environment_id}/types/{type_identifier}

Retrieve information about a single content type.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
type_identifier
required
string

Identifies the content type by internal ID (e.g., 269202ad-1d9d-47fd-b3e8-bdb05b3e3cf0), external ID (e.g., external-id/Content-Type-123), or codename (e.g., codename/hosted_video).

Responses
200

A content type object with metadata about the type and its elements.

404

The specified content type was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.viewContentType()
  .byTypeId('269202ad-1d9d-47fd-b3e8-bdb05b3e3cf0')
  // .byTypeCodename('hosted_video')
  .toPromise();
Response samples
application/json
{
  • "id": "dd1439d5-4ee2-4895-a4e4-5b0d9d8c754e",
  • "codename": "new_article",
  • "external_id": "custom-content-type-id",
  • "last_modified": "2021-06-17T06:28:11.6503569Z",
  • "name": "Article",
  • "content_groups": [
    • {
      • "id": "00000000-0000-0000-0000-000000000000",
      • "name": "Content",
      • "codename": "content"
      },
    • {
      • "id": "0acae5f5-5479-46e9-aad0-9481abb4dcab",
      • "name": "Author",
      • "codename": "author"
      },
    • {
      • "id": "b619a436-4e27-4cf3-8e42-c54ad9fccef7",
      • "name": "URL",
      • "codename": "url"
      }
    ],
  • "elements": [
    • {
      • "snippet": {
        • "id": "b14f8a4a-229d-4429-9474-4d6b9789cb95"
        },
      • "type": "snippet",
      • "id": "4e8b4583-f4f9-4db8-b9e5-683a9ed8cac6",
      • "codename": "snippet_with_title_element",
      • "is_non_localizable": false,
      • "content_group": {
        • "id": "00000000-0000-0000-0000-000000000000"
        }
      },
    • {
      • "maximum_text_length": null,
      • "maximum_image_size": null,
      • "allowed_content_types": [
        • {
          }
        ],
      • "allowed_item_link_types": [ ],
      • "image_width_limit": null,
      • "image_height_limit": null,
      • "allowed_image_types": "any",
      • "allowed_blocks": [
        • "text",
        • "tables",
        • "components-and-items"
        ],
      • "allowed_formatting": [ ],
      • "allowed_text_blocks": [
        • "paragraph",
        • "heading-two",
        • "heading-three",
        • "heading-four",
        • "ordered-list",
        • "unordered-list"
        ],
      • "allowed_table_blocks": [
        • "text"
        ],
      • "allowed_table_formatting": [ ],
      • "allowed_table_text_blocks": [
        • "paragraph"
        ],
      • "name": "Content",
      • "guidelines": "Make it snappy.",
      • "is_required": true,
      • "is_non_localizable": false,
      • "type": "rich_text",
      • "id": "23375e4a-2ed8-42bf-aa3a-dfb32e6a42ec",
      • "codename": "content",
      • "content_group": {
        • "id": "00000000-0000-0000-0000-000000000000"
        }
      },
    • {
      • "item_count_limit": {
        • "value": 1,
        • "condition": "at_least"
        },
      • "allowed_content_types": [
        • {
          }
        ],
      • "name": "Author",
      • "guidelines": "Select the author or authors.",
      • "is_required": true,
      • "is_non_localizable": false,
      • "type": "modular_content",
      • "id": "02249cf0-e9db-4e96-a582-479a2650fbc1",
      • "codename": "author",
      • "content_group": {
        • "id": "0acae5f5-5479-46e9-aad0-9481abb4dcab"
        }
      },
    • {
      • "depends_on": {
        • "snippet": {
          },
        • "element": {
          }
        },
      • "name": "URL",
      • "guidelines": "If needed, provide a custom URL slug.",
      • "is_required": true,
      • "is_non_localizable": false,
      • "type": "url_slug",
      • "id": "4a90f541-2de4-4a69-b1ef-fe53c6abf0f4",
      • "codename": "url",
      • "content_group": {
        • "id": "b619a436-4e27-4cf3-8e42-c54ad9fccef7"
        }
      }
    ]
}

Modify a content type

patch/projects/{environment_id}/types/{type_identifier}

Modify how existing content types and their elements are set up.

You can modify content types and their element configuration using the following operations:

  • addInto operation to add new objects. For example, add an element or content group to the content type, or add an option to a multiple choice element.
  • move operation to reorder objects. For example, change the position of an element or content group within the content type, or the position of a multiple choice element option.
  • remove operation to delete objects. For example, delete an element or content group from the content type, or delete a specific multiple choice element option.
  • replace operation to update values. For example, replace the value of a specific object property such as a codename.

To apply the operations on the content type's elements or content groups, you need to specify a path to the element or content group using a {path_reference}. Path references can use internal IDs, codenames, or external IDs.

  • id:5eb3d03e-c69d-4e93-b4cc-76f453271386
  • codename:my_text_element
  • external_id:id_from_external_source – Special characters such as slashes (/) need to be escaped. For example, to reference an object using its external ID of my/value, you use a path reference of external_id:my/value.
SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
type_identifier
required
string

Identifies the content type by internal ID (e.g., 269202ad-1d9d-47fd-b3e8-bdb05b3e3cf0), external ID (e.g., external-id/Content-Type-123), or codename (e.g., codename/hosted_video).

Request Body schema: application/json
required

The operations to perform on the specified content type and its elements.

Array
op
required
string

Specifies the operation to perform.

  • addInto to add new objects
  • move to reorder objects
  • remove to delete objects
  • replace to modify object properties
path
string

Specifies where to add the new object or property. The exact path depends on what you are trying to add and where. For example, if you want to add a property to an element, you need to provide a {path_reference} for the element.

  • To add a new element, set path to /elements.
  • To add a new content group, set path to /content_groups.
  • To add an allowed content type to a rich text or linked items element, set path to /elements/{path_reference}/allowed_content_types.
  • To add an allowed element to a custom element, set path to /elements/{path_reference}/allowed_elements.
  • To add a new multiple choice option, set path to /elements/{path_reference}/options.
  • To add a block so it can be used in a rich text element, set path to /elements/{path_reference}/allowed_blocks.
required
Array of StringArray (strings) or Asset type element (object) or Content group (object) or Content type snippet element (object) or Custom type element (object) or Date & time type element (object) or Guidelines type element (object) or Linked items type element (object) or MultipleChoiceOption (object) or Multiple choice type element (object) or Number type element (object) or Reference (object) or Rich text type element (object) or TaxonomyTypeElement (object) or TextTypeElement (object) or UrlSlugTypeElement (object) or SubpagesTypeElement (object)

The object to add. The value depends on the selected path:

  • To add a new element, use a content element object.
  • To add a new content group, use a content group object.
  • To add an allowed content type to a rich text or linked items element, use a reference object that points to a specific content type.
  • To add an allowed element to a custom element, use a reference object that points to the specific element.
  • To add an option to a multiple choice element, use an option object.
  • To add an allowed block, text block, or text formatting to a rich text element, use an array of strings to specify its value.
object

An optional reference to the object before which you want to add the new object.

For example, to add an element or multiple choice option before an existing element or option named "Text", you can set before to {codename: text}.

The before and after properties are mutually exclusive.

object

An optional reference to the object after which you want to add the new object.

For example, to add an element or multiple choice option after an existing element or option named "Text", you can set after to {codename: text}.

The before and after properties are mutually exclusive.

Responses
200

The modified content type.

400

The specified request body is invalid.

404

The specified content type was not found.

Request samples
application/json
[
  • {
    • "op": "replace",
    • "path": "/name",
    • "value": "A new type name"
    },
  • {
    • "op": "replace",
    • "path": "/elements/codename:my_text_element/guidelines",
    • "value": "Here you can tell users how to fill in the element."
    },
  • {
    • "op": "addInto",
    • "path": "/elements",
    • "value": {
      • "name": "My title",
      • "type": "text",
      • "guidelines": "Title of the article in plain text.",
      • "external_id": "my-title-id"
      }
    },
  • {
    • "op": "remove",
    • "path": "/elements/id:0b2015d0-16ae-414a-85f9-7e1a4b3a3eae"
    },
  • {
    • "op": "remove",
    • "path": "/elements/external_id:my_multiple_choice/options/codename:my_option"
    },
  • {
    • "op": "remove",
    • "path": "/elements/id:e94fab1f-c2c1-4f4a-b36c-3f7a0808d2b8/allowed_blocks/text"
    },
  • {
    • "op": "move",
    • "path": "/elements/codename:my_text_element",
    • "after": {
      • "external_id": "my-title-id"
      }
    },
  • {
    • "op": "move",
    • "path": "/elements/external_id:my-multiple-choice-id/options/id:d66ffa49-86ff-eeaa-c33b-e5d9eefe8b81",
    • "before": {
      • "id": "523e6231-8d80-a158-3601-dffde4e64a78"
      }
    }
]
Response samples
application/json
{
  • "id": "2b4aa3ad-f008-45a2-9561-7483557facce",
  • "codename": "my_article",
  • "last_modified": "2019-12-11T15:51:52.7389684Z",
  • "name": "A new type name",
  • "content_groups": [ ],
  • "elements": [
    • {
      • "mode": "multiple",
      • "options": [
        • {
          },
        • {
          }
        ],
      • "name": "My multiple choice element",
      • "guidelines": "",
      • "type": "multiple_choice",
      • "id": "87924912-4861-aa84-176a-1eae7b22529b",
      • "codename": "my_multiple_choice_element",
      • "external_id": "my-multiple-choice-id",
      • "is_non_localizable": false
      },
    • {
      • "name": "My title",
      • "guidelines": "Title of the article in plain text.",
      • "type": "text",
      • "external_id": "my-title-id",
      • "id": "eacf283d-7e60-57b9-a68e-91180bfebb6d",
      • "codename": "my_title",
      • "is_non_localizable": false
      },
    • {
      • "name": "My text element",
      • "guidelines": "Here you can tell users how to fill in the element.",
      • "type": "text",
      • "id": "116a2441-6441-7124-c85b-46a4fef5dcb9",
      • "codename": "my_text_element",
      • "is_non_localizable": false
      },
    • {
      • "maximum_text_length": null,
      • "maximum_image_size": null,
      • "allowed_content_types": [ ],
      • "allowed_item_link_types": [ ],
      • "image_width_limit": null,
      • "image_height_limit": null,
      • "allowed_image_types": "any",
      • "allowed_blocks": [
        • "tables"
        ],
      • "name": "Rich text",
      • "guidelines": null,
      • "is_required": false,
      • "is_non_localizable": false,
      • "type": "rich_text",
      • "id": "e94fab1f-c2c1-4f4a-b36c-3f7a0808d2b8",
      • "codename": "rich_text"
      }
    ]
}

Delete a content type

delete/projects/{environment_id}/types/{type_identifier}

Delete an unused content type.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
type_identifier
required
string

Identifies the content type by internal ID (e.g., 269202ad-1d9d-47fd-b3e8-bdb05b3e3cf0), external ID (e.g., external-id/Content-Type-123), or codename (e.g., codename/hosted_video).

Responses
204

The specified content type was deleted.

400

The specified type is used by content items and cannot be deleted.

404

The specified type was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteContentType()
  .byTypeId('269202ad-1d9d-47fd-b3e8-bdb05b3e3cf0')
  // .byTypeCodename('hosted_video')
  .toPromise();
Response samples
application/json
{
  • "request_id": "|6374648c6c8f18449b027b68dad7808a.f72d851f_",
  • "error_code": 0,
  • "message": "Type 'Article (d622fc28-5202-511a-9dbf-a3ee363b6c7c)' is still used and cannot be archived."
}

Content type snippets

The content type snippet model is structurally identical to the content type model with these exceptions:

  1. Snippets cannot contain the URL slug and content type snippet elements.
  2. Snippets cannot specify their own content groups.

You can reference snippets in your content types by using the content type snippets element. The snippet element can also be assigned to a content group for a better authoring experience.

Add a content type snippet

post/projects/{environment_id}/snippets

Create a new snippet.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

The content type snippet to be added.

codename
string [ 1 .. 50 ] characters

The content type snippet's codename. Unless set while creating the content type snippet, it is initially generated from the snippet's name and can later be modified.

name
required
string [ 1 .. 50 ] characters

Display name of the content type snippet.

required
Array of any unique

Elements within the snippet.

external_id
string

The content type snippet's external ID. Only present if defined when adding the snippet.

Responses
201

The created content type snippet.

400

The specified request body is invalid.

Request samples
application/json
{
  • "name": "Metadata",
  • "codename": "my_metadata",
  • "external_id": "my_metadata_elements",
  • "elements": [
    • {
      • "name": "Meta title",
      • "codename": "my_metadata__meta_title",
      • "guidelines": "Length: 30–60 characters",
      • "type": "text",
      • "external_id": "my-meta-title"
      },
    • {
      • "name": "Meta description",
      • "codename": "my_metadata__meta_description",
      • "guidelines": "Length: 70-150 characters",
      • "type": "text",
      • "external_id": "my-meta-description"
      }
    ]
}
Response samples
application/json
{
  • "id": "c295baa0-f910-499f-9ca2-523be657019d",
  • "codename": "my_metadata",
  • "name": "Metadata",
  • "external_id": "my_metadata_elements",
  • "elements": [
    • {
      • "name": "Meta title",
      • "guidelines": "Length: 30–60 characters",
      • "is_non_localizable": false,
      • "type": "text",
      • "id": "c44bf9dd-aa3f-41c7-b4d9-a09390e41e16",
      • "codename": "my_metadata__meta_title",
      • "external_id": "my-meta-title"
      },
    • {
      • "name": "Meta description",
      • "guidelines": "Length: 70-150 characters",
      • "is_non_localizable": false,
      • "type": "text",
      • "id": "59b9800b-81a9-4720-bef0-d4cecbaa646c",
      • "codename": "my_metadata__meta_description",
      • "external_id": "my-meta-description"
      }
    ]
}

List content type snippets

get/projects/{environment_id}/snippets

Retrieve a dynamically paginated list of content type snippets.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of content type snippets.

400

The specified continuation token is incorrect.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listContentTypeSnippets()
  .toPromise();

// Gets all pages of results
// const response = await client.listContentTypeSnippets()
//   .toAllPromise();
Response samples
application/json
{
  • "snippets": [
    • {
      • "id": "baf884be-531f-441f-ae88-64205efdd0f6",
      • "codename": "my_metadata",
      • "last_modified": "2019-10-20T12:03:17.4685693Z",
      • "name": "My metadata",
      • "elements": [
        • {
          },
        • {
          }
        ],
      • "external_id": "my-valuable-metadata"
      }
    ],
  • "pagination": {}
}

Retrieve a content type snippet

get/projects/{environment_id}/snippets/{snippet_identifier}

Retrieve information about a single content type snippet.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
snippet_identifier
required
string

Identifies a specific content type snippet by its internal ID (e.g., baf884be-531f-441f-ae88-64205efdd0f6), external ID (e.g., external-id/snippet-type-123), or codename (e.g., codename/metadata).

Responses
200

A content type snippet with metadata.

404

The specified content type snippet was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.viewContentTypeSnippet()
  .byTypeId('269202ad-1d9d-47fd-b3e8-bdb05b3e3cf0')
  // .byTypeCodename('hosted_video')
  // .byTypeExternalId('snippet-type-123')
  .toPromise();
Response samples
application/json
{
  • "id": "baf884be-531f-441f-ae88-64205efdd0f6",
  • "codename": "my_metadata",
  • "last_modified": "2018-06-20T10:25:49.133Z",
  • "name": "My metadata",
  • "external_id": "snippet-type-123",
  • "elements": [
    • {
      • "name": "Meta title",
      • "guidelines": "Length: 30–60 characters",
      • "is_non_localizable": false,
      • "type": "text",
      • "id": "09398b24-61ed-512e-5b5c-affd54a098e5",
      • "codename": "my_metadata__meta_title"
      },
    • {
      • "name": "Meta description",
      • "guidelines": "Length: 70–150 characters",
      • "is_non_localizable": false,
      • "type": "text",
      • "id": "2e555cc1-1eae-520c-189e-28548904f529",
      • "codename": "my_metadata__meta_description"
      }
    ]
}

Modify a content type snippet

patch/projects/{environment_id}/snippets/{snippet_identifier}

Modify how existing content type snippets and their elements are set up.

You can modify the content type snippets and their element configuration using the following operations:

  • addInto operation to add new objects. For example, add an element to the content type snippet, or add a multiple choice element option.
  • move operation to reorder objects. For example, change the position of an element within the content type snippet or the position of a multiple choice element option.
  • remove operation to delete objects. For example, delete an element from the content type snippet, or delete a specific multiple choice element option.
  • replace operation to update values. For example, replace the value of a specific object property such as a codename.

To apply the operations on the snippet's elements, you need to specify a path to the element or its property using a {path_reference}. Path references can use internal IDs, codenames, or external IDs.

  • id:5eb3d03e-c69d-4e93-b4cc-76f453271386
  • codename:snippet_codename__my_text_element
  • external_id:id_from_external_source – Special characters such as slashes (/) need to be escaped. For example, to reference an object using its external ID of my/value, you use a path reference of external_id:my/value.
SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
snippet_identifier
required
string

Identifies a specific content type snippet by its internal ID (e.g., baf884be-531f-441f-ae88-64205efdd0f6), external ID (e.g., external-id/snippet-type-123), or codename (e.g., codename/metadata).

Request Body schema: application/json
required

The operations to perform on the specified content type snippet and its elements.

Array
op
required
string

Specifies the operation to perform.

  • addInto to add new objects
  • move to reorder objects
  • remove to delete objects
  • replace to modify object properties
path
string

Specifies where to add the new object or property. The exact path depends on what you are trying to add and where. For example, if you want to add a property to an element, you need to provide a {path_reference} for the element.

  • To add a new element, set path to /elements.
  • To add an allowed content type to a rich text or linked items element, set path to /elements/{path_reference}/allowed_content_types.
  • To add an allowed element to a custom element, set path to /elements/{path_reference}/allowed_elements.
  • To add a new multiple choice option, set path to /elements/{path_reference}/options.
required
Asset type element (object) or Custom type element (object) or Date & time type element (object) or Guidelines type element (object) or Linked items type element (object) or Multiple choice type element (object) or MultipleChoiceOption (object) or Number type element (object) or Rich text type element (object) or TaxonomyTypeElement (object) or TextTypeElement (object)

The object to add. The value depends on the selected path:

  • To add a new element, use a content element object.
  • To add an allowed content type to a rich text or linked items element, use a reference object that points to a specific content type.
  • To add an allowed element to a custom element, use a reference object that points to the specific element with this content type snippet.
  • To add an option to a multiple choice element, use an option object.
  • To add an allowed block, text block, or text formatting to a rich text element, use an array of strings to specify its value.

You cannot add a URL slug element, subpages element, or another content type snippet element as new objects into content type snippets.

object

An optional reference to the object before which you want to add the new object.

For example, to add a content element or option before an existing element or option named "Text", you can set before to {"codename": "snippet_codename__text"}.

The before and after properties are mutually exclusive.

object

An optional reference to the object after which you want to add the new object.

For example, to add a content element or option after an existing element or option named "Text", you can set after to {"codename": "snippet_codename__text"}.

The before and after properties are mutually exclusive.

Responses
200

The modified content type snippet and its metadata.

400

The specified set of operations is invalid.

404

The specified content type snippet was not found.

Request samples
application/json
[
  • {
    • "op": "replace",
    • "path": "/name",
    • "value": "A new snippet name"
    },
  • {
    • "op": "replace",
    • "path": "/elements/codename:my_metadata__my_meta_description/guidelines",
    • "value": "Length: 70-150 characters."
    },
  • {
    • "op": "addInto",
    • "path": "/elements",
    • "value": {
      • "name": "My meta title",
      • "type": "text",
      • "guidelines": "Length: 30–60 characters.",
      • "external_id": "my-meta-title-id"
      }
    },
  • {
    • "op": "remove",
    • "path": "/elements/id:0b2015d0-16ae-414a-85f9-7e1a4b3a3eae"
    },
  • {
    • "op": "remove",
    • "path": "/elements/external_id:my_multiple_choice/options/codename:my_option"
    },
  • {
    • "op": "move",
    • "path": "/elements/codename:my_metadata_snippet__my_meta_title",
    • "after": {
      • "codename": "my_metadata_snippet__my_meta_description"
      }
    },
  • {
    • "op": "move",
    • "path": "/elements/external_id:my-multiple-choice-id/options/id:8e6ec8b1-6510-4b9b-b4be-6c977f4bdfbc",
    • "before": {
      • "id": "6bfe5a60-5cc2-4303-8f72-9cc53431046b"
      }
    }
]
Response samples
application/json
{
  • "id": "c8fcc464-b937-4558-a386-c1e25aa93813",
  • "codename": "my_metadata_snippet",
  • "last_modified": "2019-08-06T09:19:12.241774Z",
  • "external_id": "my-metadata-snippet-id",
  • "name": "A new snippet name",
  • "elements": [
    • {
      • "maximum_text_length": {
        • "value": 150,
        • "applies_to": "characters"
        },
      • "name": "My meta description",
      • "guidelines": "Length: 70-150 characters.",
      • "is_required": false,
      • "is_non_localizable": false,
      • "type": "text",
      • "id": "f79ad793-b01d-42b0-b06c-7043cd9b6f31",
      • "codename": "my_metadata_snippet__my_meta_description"
      },
    • {
      • "maximum_text_length": null,
      • "name": "My meta title",
      • "guidelines": "Length: 30–60 characters.",
      • "is_required": false,
      • "is_non_localizable": false,
      • "type": "text",
      • "external_id": "my-meta-title-id",
      • "id": "0eb2bcda-5b9f-4425-b9e1-c7679356e456",
      • "codename": "my_metadata_snippet__my_meta_title"
      },
    • {
      • "mode": "single",
      • "options": [
        • {
          },
        • {
          }
        ],
      • "name": "My multiple choice",
      • "guidelines": null,
      • "is_required": false,
      • "is_non_localizable": false,
      • "id": "fcc30f1e-9abf-41da-8693-ed89f3be438d",
      • "codename": "my_metadata_snippet__my_multiple_choice",
      • "type": "multiple_choice",
      • "external_id": "my-multiple-choice-id"
      }
    ]
}

Delete a content type snippet

delete/projects/{environment_id}/snippets/{snippet_identifier}

Delete an unused content type snippet.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
snippet_identifier
required
string

Identifies a specific content type snippet by its internal ID (e.g., baf884be-531f-441f-ae88-64205efdd0f6), external ID (e.g., external-id/snippet-type-123), or codename (e.g., codename/metadata).

Responses
204

The specified snippet was deleted.

400

The specified snippet is still used in one or more content types.

404

The specified content type snippet was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteContentTypeSnippet()
  .byTypeId('baf884be-531f-441f-ae88-64205efdd0f6')
  // .byTypeCodename('metadata')
  // .byTypeExternalId('snippet-type-123')
  .toPromise();
Response samples
application/json
{
  • "request_id": "|e7fd2e620a1e6445ab42f555d8fd7b6f.1c90015b_",
  • "error_code": 0,
  • "message": "Type 'Metadata (baf884be-531f-441f-ae88-64205efdd0f6)' is still used and cannot be archived."
}

Elements in content types

When you retrieve or update content types, you will work with a set of elements.

Asset type element

Asset element used in a content type.

name
required
string [ 1 .. 50 ] characters

The element's display name.

type
required
string

The element's type.

Allowed value Description
asset

Specifies the asset type element.

id
string

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

object

Specifies the limitation for the number of assets allowed within the element.

maximum_file_size
integer <int32>

Specifies the maximum file size in bytes.

allowed_file_types
string

Specifies the allowed file types.

Enum Value Description
adjustable

For images that that support image transformation

any

For any file types.

object

Specifies the width limitation for the asset.

object

Specifies the height limitation for the asset.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

object

Specifies the element's initial value.

Renditions are currently not supported in the default value.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "name": "Photo",
  • "type": "asset",
  • "id": "30ca5bc8-4f2a-47b9-a9e7-0d13a2935e10",
  • "codename": "photo",
  • "external_id": "profile-picture",
  • "guidelines": "Optional photo of the author.",
  • "asset_count_limit": {
    • "value": 1,
    • "condition": "exactly"
    },
  • "maximum_file_size": 262144,
  • "allowed_file_types": "adjustable",
  • "image_width_limit": null,
  • "image_height_limit": null,
  • "is_required": "true",
  • "is_non_localizable": "false",
  • "default": {
    • "global": {
      • "value": [
        • {
          }
        ]
      }
    },
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Content type snippet element

The content type snippet elements contain the snippet property with a reference to a specific content type snippet.

Learn more about reusing groups of elements with snippets.

required
object

The element's reference to a specific content type snippet.

type
required
string

The element's type.

Allowed value Description
snippet

Specifies the content type snippet element.

id
required
string <uuid>

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Initially generated from the snippet's name.

When modifying content types, you can reference snippet elements by their codename provided the element already exists before making the request.

external_id
string

The element's external ID.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "snippet": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "type": "snippet",
  • "id": "15e39f98-1586-4f05-b260-36684600b205",
  • "codename": "seo_metadata",
  • "external_id": "my-seo-metadata",
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Custom type element

Create your own custom element, or see the integrations topic on GitHub and the custom elements overview to find custom elements you can use or customize for your scenario.

name
required
string [ 1 .. 50 ] characters

The element's display name.

type
required
string

The element's type.

Allowed value Description
custom

Specifies the custom element.

id
string <uuid>

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

source_url
required
string

Absolute URL that hosts your custom element.

json_parameters
string

Optional parameters that allow you to use the element in different content types or provide customizable layout.

The value must be valid a stringified JSON.

Array of objects unique

Specifies the elements that this custom element can read from.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "name": "Color picker",
  • "type": "custom",
  • "id": "2f9dea65-a6d3-49e7-9297-56d8034e8f42",
  • "codename": "color_picker",
  • "external_id": "color-picker",
  • "guidelines": "Always pick colors based on the brand manuals.",
  • "is_required": "false",
  • "is_non_localizable": "false",
  • "source_url": "https://github.com/kontent-ai/custom-element-template-react",
  • "json_parameters": "{\\\"brand_colors_only\\\":\\\"true\\\"}",
  • "allowed_elements": [
    • {
      • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
      }
    ],
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Date and time type element

name
required
string [ 1 .. 50 ] characters

The element's display name.

guidelines
string

The element's guidelines, providing instructions on what to fill in.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

type
required
string

The element's type.

Allowed value Description
date_time

Specifies the date & time element.

id
string <uuid>

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

object

Specifies the element's initial value.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "name": "Birth date",
  • "guidelines": "Proivde exact birth date and time with one minute precision.",
  • "is_required": "false",
  • "is_non_localizable": "true",
  • "type": "date_time",
  • "id": "4f64afc0-5102-4fad-b564-baadb375ab73",
  • "codename": "birth_date",
  • "external_id": "birth-date",
  • "default": {
    • "global": {
      • "value": "2019-10-31T00:00:00Z"
      }
    },
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Guidelines type element

Guidelines elements do not contain the name property.

guidelines
required
string [ 1 .. 100000 ] characters

Specifies the instructions for contributors on what to insert in the other elements.

The value of the guidelines property must follow the same limitations as the value of rich text elements. In addition, the guidelines element cannot contain content items or components.

type
required
string

The element's type.

Allowed value Description
guidelines

Specifies the guidelines element.

id
string

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's id.

external_id
string

The element's external ID.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "guidelines": "<p><strong>Naming and usage</strong></p> ...",
  • "type": "guidelines",
  • "id": "19e15fe8-900a-4456-84eb-16430dc35e88",
  • "codename": "n19e15fe8_900a_4456_84eb_16430dc35e88",
  • "external_id": "additional-information",
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Linked items type element

object

Specifies the limitation for the number of items allowed within the element.

Array of objects unique

Specifies the allowed content types as an array of references to the content types.

name
required
string [ 1 .. 50 ] characters

The element's display name.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

type
required
string

The element's type.

Allowed value Description
modular_content

Specifies the linked items element.

id
string

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

object

Specifies the element's initial value.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "item_count_limit": {
    • "value": 1,
    • "condition": "exactly"
    },
  • "allowed_content_types": [
    • {
      • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
      }
    ],
  • "name": "Fun facts",
  • "guidelines": "Keep them light and fun.",
  • "is_required": "false",
  • "is_non_localizable": "false",
  • "type": "modular_content",
  • "id": "63c0a251-f455-45c8-95bd-542c1358b1a8",
  • "codename": "fun_facts",
  • "external_id": "my-fun-facts",
  • "default": {
    • "global": {
      • "value": [
        • {
          }
        ]
      }
    },
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Number type element

name
required
string [ 1 .. 50 ] characters

The element's display name.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

type
required
string

The element's type.

Allowed value Description
number

Specifies the number element.

id
string <uuid>

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

object

Specifies the element's initial value.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "name": "Number",
  • "guidelines": "Provide a number.",
  • "is_required": "false",
  • "is_non_localizable": "true",
  • "type": "number",
  • "id": "b18cbb42-9649-4870-b2d6-805238a34ae9",
  • "codename": "number",
  • "external_id": "my-number",
  • "default": {
    • "global": {
      • "value": 42
      }
    },
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Multiple choice type element

mode
required
string

Defines whether the multiple choice element acts as a single choice (shown as radio buttons in the UI) or multiple choice (shown as checkboxes in the UI).

Enum Value Description
multiple

The multiple choice element allows selecting multiple options.

single

The multiple choice element allows selecting a single option.

required
Array of objects unique

The element's multiple choice options.

name
required
string [ 1 .. 50 ] characters

The element's display name.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

type
required
string

The element's type.

Allowed value Description
multiple_choice

Specifies the multiple choice element.

id
string

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

object

Specifies the element's initial value.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "mode": "single",
  • "options": [
    • {
      • "id": "6bfe5a60-5cc2-4303-8f72-9cc53431046b",
      • "codename": "option_name",
      • "external_id": "custom-option-identifier",
      • "name": "Option name"
      }
    ],
  • "name": "Product state",
  • "guidelines": "Specify all possible options.",
  • "is_required": "true",
  • "is_non_localizable": "true",
  • "type": "multiple_choice",
  • "id": "fcc30f1e-9abf-41da-8693-ed89f3be438d",
  • "codename": "product_state",
  • "external_id": "product-state-id",
  • "default": {
    • "global": {
      • "value": [
        • {
          }
        ]
      }
    },
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Rich text type element

object

Specifies the maximum text length.

maximum_image_size
integer or null <int32>

Specifies the maximum image size in bytes.

Array of objects unique

Specifies a list of allowed content types of components and linked items as an array of references. To allow all content types, leave the array empty.

Array of objects unique

Specifies content types of items that are allowed to be used in text links as an array of references. The limitation applies to links both in text and in tables. To allow all content types, leave the array empty.

allowed_blocks
Array of strings or null

Specifies which types of blocks are allowed in the rich text element. To allow all blocks, use an empty array.

Enum Value Description
images

Allows inserting images in the rich text.

text

Allows inserting text characters in the rich text.

tables

Allows inserting tables in the rich text.

… 1 more
allowed_text_blocks
Array of strings or null

Specifies which text blocks are allowed in the rich text element. To allow all text blocks, use an empty array.

Enum Value Description
paragraph

Allows to structure the text in paragraphs.

heading-one

Allows to structure the text using first-level headings.

heading-two

Allows to structure the text using second-level headings.

… 6 more
allowed_formatting
Array of strings or null

Specifies which text formatting is allowed in the rich text element. To allow all formatting, use an empty array. To allow only plaintext, use ["unstyled"].

The unstyled value must precede any other values in the list.

Enum Value Description
unstyled

Allows text without any formatting.

bold

Allows bold text formatting.

italic

Allows italic text formatting.

… 4 more
allowed_table_blocks
Array of strings or null

Specifies which blocks are allowed in tables in the rich text element.

Either use ["text"] to allow only text or leave the array empty to allow both text and images.

Enum Value Description
images

Allows inserting images in tables in the rich text.

text

Allows inserting text characters in tables in the rich text.

allowed_table_text_blocks
Array of strings or null

Specifies which text blocks are allowed in tables in the rich text element. You can allow paragraphs, headings, and lists. To allow all text blocks, leave the array empty.

Enum Value Description
paragraph

Allows to structure the text in tables in paragraphs.

heading-one

Allows to structure the text in tables using first-level headings.

heading-two

Allows to structure the text in tables using second-level headings.

… 6 more
allowed_table_formatting
Array of strings or null

Specifies which text formatting is allowed in tables in the rich text element. To allow all formatting, leave the array empty. To allow only plaintext, use ["unstyled"].

The unstyled value must precede any other values in the list.

Enum Value Description
unstyled

Allows text in tables without any formatting.

bold

Allows bold text formatting in tables.

italic

Allows italic text formatting in tables.

… 4 more
object

Specifies the width limitation for images.

object

Specifies the height limitation for images.

allowed_image_types
string

Specifies which image types are allowed.

Enum Value Description
adjustable

Images that that support image transformation

any

Any image type

name
required
string [ 1 .. 50 ] characters

The element's display name.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages. Rich text elements cannot be set as non-localizable.

type
required
string

The element's type.

Allowed value Description
rich_text

Specifies the rich text element.

id
string

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "maximum_text_length": {
    • "value": 60,
    • "applies_to": "characters"
    },
  • "maximum_image_size": 1048576,
  • "allowed_content_types": [
    • {
      • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
      }
    ],
  • "allowed_item_link_types": [
    • {
      • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
      }
    ],
  • "allowed_blocks": [
    • "text"
    ],
  • "allowed_text_blocks": [
    • "paragraph",
    • "heading-one",
    • "heading-two"
    ],
  • "allowed_formatting": [
    • "unstyled",
    • "bold",
    • "italic"
    ],
  • "allowed_table_blocks": [
    • "text"
    ],
  • "allowed_table_text_blocks": [
    • "paragraph",
    • "heading-one",
    • "heading-two"
    ],
  • "allowed_table_formatting": [
    • "unstyled",
    • "bold",
    • "italic"
    ],
  • "image_width_limit": {
    • "value": 256,
    • "condition": "at_least"
    },
  • "image_height_limit": {
    • "value": 256,
    • "condition": "at_least"
    },
  • "allowed_image_types": "adjustable",
  • "name": "string",
  • "guidelines": "string",
  • "is_required": true,
  • "is_non_localizable": "false",
  • "type": "rich_text",
  • "id": "string",
  • "codename": "string",
  • "external_id": "custom-rich-text-identifier",
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Subpages type element

The Subpages element requires Web Spotlight.

object

Specifies the limitation for the number of items allowed within the element.

Array of objects unique

Specifies allowed file types as an array of references to the content types.

name
required
string [ 1 .. 50 ] characters

The element's display name.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

type
required
string

The element's type.

id
string

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

object

Specifies the element's initial value.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "item_count_limit": {
    • "value": 1,
    • "condition": "exactly"
    },
  • "allowed_content_types": [
    • {
      • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
      }
    ],
  • "name": "Articles",
  • "guidelines": "Select pages to show under this navigation item.",
  • "is_required": "true",
  • "is_non_localizable": "false",
  • "type": "subpages",
  • "id": "50b48cc6-ae3b-46f8-8239-fd1eb9f30afe",
  • "codename": "articles",
  • "external_id": "article-subpages",
  • "default": {
    • "global": {
      • "value": [
        • {
          }
        ]
      }
    },
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Taxonomy type element

name
string [ 1 .. 50 ] characters

The element's display name. If not provided when adding the element to a content type, the name is taken from the taxonomy groups name.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

required
object

Specifies a reference to the taxonomy group that the element uses.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

object

Specifies the limitation for the number of terms that can be selected in the element.

type
required
string

The element's type.

id
string

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the name of the taxonomy group specified in the taxonomy_group property.

external_id
string

The element's external ID.

object

Specifies the element's initial value.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "name": "Personas",
  • "guidelines": "Be sure to be in the correct group",
  • "taxonomy_group": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "is_required": "false",
  • "is_non_localizable": "false",
  • "term_count_limit": {
    • "value": 1,
    • "condition": "exactly"
    },
  • "type": "taxonomy",
  • "id": "fdcdd09e-7599-4f24-b8eb-fdf318e1072e",
  • "codename": "personas",
  • "external_id": "business-personas",
  • "default": {
    • "global": {
      • "value": [
        • {
          }
        ]
      }
    },
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Text type element

name
required
string [ 1 .. 50 ] characters

The element's display name.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

is_required
boolean

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

type
required
string

The element's type.

id
string

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

object

Specifies the maximum text length.

object

Specifies a regular expression pattern used to validate the element's value.

object

Specifies the element's initial value.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "name": "Title",
  • "guidelines": "Keep it short.",
  • "is_required": "false",
  • "is_non_localizable": "true",
  • "type": "text",
  • "id": "7dc115d0-e9f8-4947-9cfb-9a26485975ae",
  • "codename": "title",
  • "external_id": "my-text-element",
  • "maximum_text_length": {
    • "value": 60,
    • "applies_to": "characters"
    },
  • "validation_regex": {
    • "regex": "^(https?:\\/\\/(?:www\\.|(?!www)))?[a-z0-9]+([\\-\\.]{1}[a-z0-9]+)*\\.[a-z]{2,5}(:[0-9]{1,5})?(\\/.*)?$",
    • "flags": "i",
    • "validation_message": "Type a valid web URL such as https://example.org.",
    • "is_active": "true"
    },
  • "default": {
    • "global": {
      • "value": "The greatest title"
      }
    },
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

URL slug type element

Learn more about the use of URL slugs and content type snippets within Kontent.ai.

name
required
string [ 1 .. 50 ] characters

The element's display name.

required
object

Specifies the text element that provides the default value to the URL slug element. The dependent text element can be part of a content type snippet.

guidelines
string or null

The element's guidelines, providing instructions on what to fill in.

is_required
boolean or null

Determines whether the element must be filled in.

is_non_localizable
boolean

Determines whether the element uses the same value in all languages.

type
required
string

The element's type.

id
string

The element's internal ID.

codename
string [ 1 .. 60 ] characters

The element's codename. Unless specified, initially generated from the element's name.

external_id
string

The element's external ID.

object

Specifies a regular expression pattern used to validate the element's value.

object

Reference to the content group the element is used in.

The content_group property is present only if one or more content groups are defined in the content type.

{
  • "name": "URL slug",
  • "depends_on": {
    • "element": {
      • "id": "c7c3b834-2222-5677-89c4-b46f04489109"
      },
    • "snippet": {
      • "id": "67faca73-bfd3-4600-b6c4-9cc91cc8d85f"
      }
    },
  • "guidelines": "Auto-generated from Title. Only change if necessary.",
  • "is_required": "false",
  • "is_non_localizable": "false",
  • "type": "url_slug",
  • "id": "8f43fd1b-e11d-494b-a85f-478db1703c21",
  • "codename": "url_slug",
  • "external_id": "my-url-slug",
  • "validation_regex": {
    • "regex": "^(https?:\\/\\/(?:www\\.|(?!www)))?[a-z0-9]+([\\-\\.]{1}[a-z0-9]+)*\\.[a-z]{2,5}(:[0-9]{1,5})?(\\/.*)?$",
    • "flags": "i",
    • "validation_message": "Type a valid web URL such as https://example.org.",
    • "is_active": "true"
    },
  • "content_group": {
    • "id": "ad1b8cce-94d6-4682-a9ff-393d494e3a02"
    }
}

Elements in variants and assets

When you retrieve or update language variants or assets, you will work with a set of elements. The set contains the elements as defined in the content type or asset type. The elements come in the form of key-value pairs and contain only information about their values, not their type.

Currently, only the taxonomy element is supported in the assets.

About element identifiers

In API responses, the Management API will always reference content elements with their internal IDs. When creating or updating language variants or assets via the API, you can reference content elements by their internal IDs or codenames.

Asset element

required
object
required
Array of objects or objects unique

The value of asset elements is an array of Reference objects, each representing a single asset. Every asset can be referenced only once. You can also reference the asset's renditions by the renditions property. Renditions are specific to images only.

When retrieving asset elements, the Management API will always reference assets with their internal IDs. When updating asset elements via the API, you can reference an asset by its internal ID or external ID. Also, you can reference a rendition by its internal ID or external ID.

{
  • "element": {
    • "id": "975bf280-fd91-488c-994c-2f04416e5ee3"
    },
  • "value": [
    • {
      • "id": "6c332099-56fb-46df-95e7-2db2983a1ea3",
      • "renditions": [
        • {
          }
        ]
      },
    • {
      • "id": "719a646b-037d-426b-9ff5-cc519daa5473",
      • "renditions": [
        • {
          }
        ]
      }
    ]
}

Custom element

Create your own custom element, or see the integrations topic on GitHub and the custom elements overview to find custom elements you can use or customize for your scenario.

required
object
value
required
string or null <= 200000 characters

The format depends on the custom element you use.

When retrieving and updating custom elements, the format of the value will be identical for both GET and PUT operations.

searchable_value
string or null <= 200000 characters

Plain text searchable value used for searching in the content items list. Do not use any markup or JSON here to allow a correct search.

When retrieving and updating custom elements, the format of the value will be identical for both GET and PUT operations.

{
  • "element": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "value": "#00ffff",
  • "searchable_value": "#00ffff #0ff Cyan Aqua"
}

Date and time element

required
object
value
required
string or null <date-time>

Time in this element is interpreted as UTC and stored as an ISO-8601 formatted string.

When retrieving and updating date & time elements, the format of the value will be identical for both GET and PUT operations.

display_timezone
string or null

IANA time zone name used to display time offset of the date & time element in the UI.

The time zone doesn't modify the date specified in value.

If omitted, the value defaults to null and the date in the UI is displayed in a local time zone.

Obsolete values: "America/Ojinaga", "Asia/Qyzylorda", "Europe/Kiev".

Allowed values: "Africa/Abidjan" "Africa/Accra" "Africa/Addis_Ababa" … 319 more
{
  • "element": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "value": "2017-10-31T00:00:00Z",
  • "display_timezone": "Europe/London"
}

Linked items element

required
object
required
Array of objects

The value of Linked items elements is an array of Reference objects. Each reference represents a single content item. Every content item can be referenced only once.

When retrieving Linked items elements, the Management API will always reference content items with their internal IDs. When updating Linked items elements via the API, you can reference a content item by its internal ID, codename, or external ID.

{
  • "element": {
    • "id": "18eeb93a-445a-4b9a-befc-bef10f508056"
    },
  • "value": [
    • {
      • "id": "6c332099-56fb-46df-95e7-2db2983a1ea3"
      },
    • {
      • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb"
      }
    ]
}

Multiple choice element

required
object
required
Array of objects unique

The value of Multiple choice elements is an array of Reference objects. Each reference represents one of the multiple choice options, each with a unique identifier.

If the multiple choice element is configured as single option (i.e., radio buttons), its value array must contain a reference to exactly one option. When configured as multiple option (i.e., checkboxes), the array can contain references to as many options as are defined in the content type. In case no option is selected, the value of the element will be an empty array.

When retrieving Multiple choice elements, the Management API will always reference the multiple choice options with their internal IDs. When updating multiple choice elements via the API, you can reference an option by its internal ID or codename.

{
  • "element": {
    • "id": "975bf280-fd91-488c-994c-2f04416e5ee3"
    },
  • "value": [
    • {
      • "id": "6c332099-56fb-46df-95e7-2db2983a1ea3"
      },
    • {
      • "id": "2c03182a-223a-46b1-a02d-b36d019d39d2"
      }
    ]
}

Number element

required
object
value
required
number or null <float>

When retrieving and updating Number elements, the format of the value will be identical for both GET and PUT operations.

{
  • "element": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "value": 3.14159
}

Rich text element

required
object
value
required
string <= 100000 characters

By default, if there is no text, the rich text value is a single empty paragraph: <p><br/></p>. The value can contain HTML formatted text, specific HTML elements, tags, and attributes, and must form a valid HTML5 fragment.

Nesting HTML elements in rich text

At the top level, only the following elements are allowed: <p>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <ul>, <ol>, <table>, <object> (for content items and components), and <figure> (for images). These top-level elements can NOT be nested except for lists (<ul> and <ol>). Text is not allowed at the top level with the exception of new lines and white space characters.

The table <td> element can alternatively contain top level elements except for <table> and <object>.

The <p>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <li>, and <td> elements can contain text and the following inline elements: <a>, <code>, <em>, <strong>, <sub>, <sup>. These elements can also contain <br/> elements for specifying line breaks.

The <a>, <code>, <em>, and <strong> inline elements can be nested but they cannot cross one another. For example, it's not allowed to open the <em> element, then the <strong> element, and then close the <em> element. Lists can be nested as long as the nested list (<ul> or <ol>) is the last HTML element of the list item, for example, <ol><li>List item<ul><li>Nested list item</li></ul></li></ol>.

For more information see the list of supported HTML elements and their syntax.

Array of objects unique

A list of components used in the rich text's value.

The components can be nested up to 6 levels deep.

{
  • "element": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "value": "... <h3>Medium roast</h3>\n<p>These exempt a <strong>stronger</strong> flavor than light <a data-item-id=\\\"f4b3fc05-e988-4dae-9ac1-a94aba566474\\\">roasts</a>. The beans are still more matte than oily<sup><a href=\\\"#footnote-1\\\">1</a></sup>.</p>\n<figure data-asset-id=\\\"66d73245-10e5-4478-93e7-5609fee3cdf7\\\"><img src=\\\"#\\\" data-asset-id=\\\"66d73245-10e5-4478-93e7-5609fee3cdf7\\\"></figure>\n<p>Caffeine contents are decreased. Medium roasts lack the <code>grainy</code> taste of lighter roasts. You also get a more balanced flavor, aroma and acidity.</p>\n<object type=\\\"application/kenticocloud\\\" data-type=\\\"component\\\" data-id=\\\"382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d\\\"></object>\n ...",
  • "components": [
    • {
      • "id": "382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d",
      • "type": {
        • "id": "f4cb13df-d61d-572e-8f3b-3afe7e3a7ea1"
        },
      • "elements": [
        • {
          },
        • {
          }
        ]
      }
    ]
}

HTML5 elements allowed in rich text

The rich text value can contain specific HTML elements, tags, and attributes, and must form a valid HTML5 fragment. Only the documented HTML attributes are supported. When transforming HTML to JSON, make sure to escape all double quotes.

Top-level elements

The following HTML elements must be used at the top level in rich text content. They can also be used within a table cell <td>.

Types HTML elements Notes
Paragraphs <p>...</p> Can contain text with inline formatting elements.
Headings <h1>...</h1>, <h2>...</h2>, <h3>...</h3>, <h4>...</h4>, <h5>...</h5>, <h6>...</h6> Can contain text with inline formatting elements.
Lists <ol><li>...</li></ol>, <ul><li>...</li></ul> Individual list items <li> can contain text with inline formatting elements.
Assets <figure ...><img ...></figure>
Tables <table><tbody><tr><td>...</td></tr></tbody></table> The <thead> and <tfoot> tags are not supported. Individual table cells <td> can contain either text with inline formatting elements, or top-level elements. Nested tables are not supported inside table cells.
Content items and components <object ...></object> Content items and components are not supported inside table cells.

Elements for inline text formatting

The following inline HTML elements can be used within the top-level elements and table cells.

Types HTML elements Notes
Bold text <strong>...</strong> The <b> tag is not supported.
Italic text <em>...</em> The <i> tag is not supported.
Superscript <sup>...</sup> Superscript and subscript are mutually exclusive.
Subscript <sub>...</sub> Superscript and subscript are mutually exclusive.
Code <code>...</code>
Links <a ...>...</a> For the list of supported <a> attributes, see Links in rich text.
Line breaks <br/>

Assets in rich text

Assets in rich text are defined by the block element <figure> which requires one of the following attributes: data-asset-id or data-asset-external-id. The data-asset-external-id attribute can also reference an object that was not yet imported into Kontent.ai. Find more about external IDs for imported content.

When inserting values in rich text, the <img> element is optional. Otherwise, the <img> element requires the attributes src and data-asset-id.

{
...
  "element": {
    "codename": "asset_referenced_by_internal_id"
  },
  "value": "<figure data-asset-id="512047f1-2f7f-45fd-9e90-e71b8feae017"><img src="#" data-asset-id="512047f1-2f7f-45fd-9e90-e71b8feae017"></figure>"
...
  "element": {
    "codename": "asset_referenced_by_internal_id"
  },
  "value": "<figure data-asset-external-id="coffee_beans"></figure>"
...
}

Components in rich text

Components in rich text are defined by the <object> block element. The <object> element requires the type, data-type, and data-id attributes.

{
...
  "element": {
    "codename": "component_referenced_by_internal_id"
  },
  "value": "<object type="application/kenticocloud" data-type="component" data-id="382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d"></object>"
...
}

For each component in the text, the rich text object's components property must hold a matching component object. When specifying components in the rich text's value property, you need to provide a unique ID (GUID) for the data-id attribute of each component.

Component object

id
required
string <uuid>

The component's ID. Must match the data-id of the component object inside the value of the rich text element.

required
object

Reference to the component's content type.

required
Array of Asset element (object) or Custom element (object) or Date & time element (object) or Linked items element (object) or Multiple choice element (object) or Number element (object) or Rich text element (object) or Taxonomy element (object) or Text element (object) or URL slug element (object) unique

The component's elements based on the specified content type.

{
  • "id": "382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d",
  • "type": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "elements": [
    • {
      • "element": {
        • "id": "975bf280-fd91-488c-994c-2f04416e5ee3"
        },
      • "value": [
        • {
          },
        • {
          }
        ]
      }
    ]
}

Nesting of components

If the inserted component contains a rich text element, the rich text element may contain more components. These nested components may contain another rich text element with more components, and so on. The components can be nested up to 6 levels deep.

{
  "element": {
    "id": "49150275-064b-5314-be6e-b93e1d7661e1"
  },
  "value": "<p>Level 1: Content in a rich text element</p>n<object type="application/kenticocloud" data-type="component" data-id="382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d"></object>",
  "components": [
    {
      "id": "382abced-bfb6-4ee9-a2d4-2c3b8cd8ba5d",
      "type": {
        "id": "f4cb13df-d61d-572e-8f3b-3afe7e3a7ea1"
      },
      "elements": [
        {
          "element": {
            "id": "0b9173d6-1c94-5fb0-a010-86eef9013fd4"
          },
          "value": "<p>Level 2: content in a nested component</p>n<object type="application/kenticocloud" data-type="component" data-id="7c1ca8b2-2fa8-41d8-be02-bf157d3fa225"></object>",
          "components": [
            {
              "id": "7c1ca8b2-2fa8-41d8-be02-bf157d3fa225",
              "type": {
                "id": "37684e4c-9303-589b-a937-c7c165171b38"
              },
              "elements": [
                {
                  "element": {
                    "id": "ff50c0e0-226e-5474-b71b-2af194edd7c4"
                  },
                  "value": "<p>Level 3: content in a nested component</p>",
                  "components": []
                }
              ]
            }
          ]
        },
        {
          "element": {
            "id": "edd22f22-ccd6-56e6-9fe2-676a7e250d8c"
          },
          "value": [
            {
              "id": "f206b928-7609-5192-bd31-6eb6aae48096"
            }
          ]
        }
      ]
    }
  ]
}

Content items in rich text

Content items in rich text are defined by the <object> block element. The <object> element requires the attributes type, data-type, and either data-id or data-external-id. The data-external-id attribute can also reference an object that has not yet been imported into Kontent.ai. Find more about external IDs for imported content.

{
...
  "element": {
    "codename": "item_referenced_by_internal_id"
  },
  "value": "<object type="application/kenticocloud" data-type="item" data-id="f4b3fc05-e988-4dae-9ac1-a94aba566474"></object>"
...
  "element": {
    "codename": "item_referenced_by_external_id"
  },
  "value": "<object type="application/kenticocloud" data-type="item" data-external-id="59713"></object>"
...
}

Links in rich text

Links in rich text are defined as the <a> element, for example, <a href="#">Link</a>. These links can be used for web URLs, email addresses, assets, and content items. For each of the link types, the <a> element supports a different set of required and optional attributes.

Links to content items

Links to content items require one of the following attributes: data-item-id or data-item-external-id. The data-item-external-id attribute can also reference an object that has not yet been imported into Kontent.ai. Find more about external IDs for imported content.

{
...
  "element": {
    "codename": "item_linked_by_internal_id"
  },
  "value": "<a data-item-id="f4b3fc05-e988-4dae-9ac1-a94aba566474">link to a content item</a>"
...
  "element": {
    "codename": "item_linked_by_external_id"
  },
  "value": "<a data-item-external-id="my-1337-article">link to another content item</a>"
...
}

Lists in rich text

Lists in rich text are defined as standard HTML lists, either ordered (<ol>) or unordered (<ul>). Each list item can contain another nested list, a piece of HTML formatted text, or be empty.

{
...
  "value": "<ol><li>A list item</li><li>Another list item<ul><li>Nested list item</li></ul></li></ol>"
...
}

Tables in rich text

Tables in rich text elements are defined as standard HTML tables with the table cells and rows contained within the <tbody> element. Individual table cells (<td>) can contain either text with inline formatting elements, or top-level elements. The tables cells and rows cannot be merged.

{
...
  "value": "<table><tbody><tr><td>Type A</td><td>Type B</td><td>Type C</td></tr>   <tr>   <td>12.4</td><td>3.14</td><td>34.1</td></tr></tbody></table>"
...
}

Subpages element

The Subpages element requires Web Spotlight.

required
object
required
Array of objects

The value of Subpages elements is an array of Reference objects. Each reference represents a single content item. Every content item can be referenced only once.

When retrieving Subpages elements, the Management API will always reference content items with their internal IDs. When updating Subpages elements via the API, you can reference a content item by its internal ID, codename, or external ID.

{
  • "element": {
    • "id": "ab121ec9-2ea3-4b59-aabc-3f9fd495a83d"
    },
  • "value": [
    • {
      • "id": "b0c75ce3-6e9b-4f93-a952-71f74e809ec4"
      },
    • {
      • "id": "cc63a341-fd78-45d3-826f-7071e3ac756e"
      }
    ]
}

Taxonomy element

required
object
required
Array of objects unique

The value of taxonomy elements is an array of Reference objects. Each reference represents a taxonomy term of a specific taxonomy group. Every taxonomy term can be referenced only once.

When retrieving taxonomy elements, the Management API will always reference taxonomy terms with their internal IDs. When updating taxonomy elements via the API, you can reference a taxonomy term by its internal ID, external ID, or codename.

{
  • "element": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "value": [
    • {
      • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
      }
    ]
}

Text element

required
object
value
required
string or null <= 100000 characters

When retrieving and updating text elements, the format of the value property will be identical for both GET and PUT operations.

{
  • "element": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "value": "Plaintext, plain and simple."
}

URL slug element

required
object
mode
required
string

Determines the element's mode of operation.

  • autogenerated means the URL slug element sets its value automatically based on the value of a specified text element.
  • custom means the URL slug element's value is not affected by changes in a specified text element and can be set manually.

You can change the text element the URL slug depends on either in the UI or via the API.

value
string

The element's value.

  • When upserting the element with the mode set to autogenerated, the value is ignored and can be omitted.
  • If the value is upserted, the element's mode changes to custom automatically.

Automatic vs. manual mode

The URL slug element can function in two modes, automatic and manual. When creating language variants in automatic mode, the system automatically generates the element's value based on the text element of your choice.

If you modify the element's value directly (either in UI or via API), the element switches to the manual mode. In this mode, the element does not react to changes made to the dependent text element. Learn about creating SEO-friendly URLs in your projects.

{
  • "element": {
    • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
    },
  • "mode": "autogenerated",
  • "value": "user-and-seo-friendly-url-slug"
}

Environments

An environment is a snapshot of your project that you can use to safely make changes to your content model and adjust your app. Because environments are isolated snapshots, they aren't meant for content production.

Use environments to update your content model and adjust your app safely. Learn how to set up, swap, and migrate using environments.

Clone an environment

post/projects/{environment_id}/clone-environment

Creates a clone of an existing environment. By default, only the user who initiated the cloning and users with the Project manager role will be active in the new environment.

We recommend you work with the new environment after the cloning is finished. Check the environment's cloning progress via API to know when the new environment is ready.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

Specify the environment's name and the roles that should be active in the new environment.

name
required
string [ 1 .. 200 ] characters

The environment's name.

roles_to_activate
Array of strings <uuid>

The user roles to activate specified by role ID. These roles will be activated in addition to the users with the Project manager role.

Responses
200

The environment cloning has started.

400

The specified request body is invalid.

Request samples
application/json
{
  • "name": "Development",
  • "roles_to_activate": [
    • "ee483b59-5a24-4010-b277-ae224c34bc71"
    ]
}
Response samples
application/json
{
  • "id": "71386f85-cddb-4cb0-aa54-988566feb9a1",
  • "management_api_key": "ey...",
  • "secured_delivery_api_key": "ey...",
  • "delivery_preview_api_key": "ey..."
}

Get status of environment cloning

get/projects/{environment_id}/environment-cloning-state

Retrieve the cloning status of the specified environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

The cloning status of the specified environment.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
    environmentId: '<YOUR_ENVIRONMENT_ID>',
    apiKey: '<YOUR_API_KEY>'
});

const response = await client.getEnvironmentCloningState()
    .toPromise();
Response samples
application/json
{
  • "cloning_state": "done"
}

Retrieve environment information

get/projects/{environment_id}

Retrieve the ID and display name of your project's environment. Using this endpoint, you can also validate your Management API key.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

Information about the specified environment.

403

The requested environment doesn't exist.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.projectInformation()
  .toPromise();
Response samples
application/json
{
  • "id": "8d20758c-d74c-4f59-ae04-ee928c0816b7",
  • "name": "Sample project",
  • "environment": "Production",
  • "is_production": "true"
}

Rename an environment

patch/projects/{environment_id}

Change the display name of an environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json

Specify the environment's name.

Array (non-empty)
op
required
string

The operation's name. The allowed operation is rename_environment.

Allowed value Description
rename_environment

Specifies the operation to rename an environment.

value
required
string

The environment's name.

Responses
200

The environment was renamed.

400

The specified request body is invalid, or the environment hasn't finished cloning yet.

Request samples
application/json
[
  • {
    • "op": "rename_environment",
    • "value": "Production"
    }
]
Response samples
application/json
{
  • "id": "4a8b44fa-785c-00ae-4d5c-029de7428cab",
  • "name": "Production",
  • "is_production": true
}

Delete an environment

delete/projects/{environment_id}

Deletes an environment from your project. If an environment is marked as production, it cannot be deleted.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
204

The environment was deleted.

400

The environment cannot be deleted. The environment is either marked as production, or being cloned.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
    environmentId: '<YOUR_ENVIRONMENT_ID>',
    apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteEnvironment()
    .toPromise();
Response samples
application/json
{
  • "request_id": "af1567cb33d85545",
  • "error_code": 233,
  • "message": "The production environment can’t be deleted."
}

Mark environment as production

put/projects/{environment_id}/mark-environment-as-production

Marks the specified environment as production. This action effectively swaps the production environment with the specified non-production environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json

Specify whether you want to enable webhooks.

enable_webhooks
boolean

Determines whether the webhooks in the specified environment should be enabled after marking the environment as production.

If not specified, the webhooks in the specified environment will be enabled.

Responses
204

The environment was successfully marked as production.

400

The environment is already marked as production.

Request samples
application/json
{
  • "enable_webhooks": "true"
}
Response samples
application/json
{
  • "request_id": "4c3b488c74c18640",
  • "error_code": 232,
  • "message": "The environment 4a8b44fa-785c-00ae-4d5c-029de7428cab is already marked as production."
}

Language variants

Language variants represent localized variants of content items. For example, when you have 2 active languages, each content item can have up to 2 variants.

Every language variant is tied to a specific content item and language. This means you need to specify a language identifier when you request the variant, even if your environment contains only one language.

If a language is deactivated, the respective content item variants cannot be retrieved via Management API and the API returns a 404 not found error.

To manage language variants via Management API, send requests to URLs based on the following patterns:

  • Item ID + Language ID: <base_URL>/items/<content_item_id>/variants/<language_id>
  • Item ID + Language codename: <base_URL>/items/<content_item_id>/variants/codename/<language_codename>
  • Item codename + Language ID: <base_URL>/items/codename/<content_item_codename>/variants/<language_id>
  • Item codename + Language codename: <base_URL>/items/codename/<content_item_codename>/variants/codename/<language_codename>
  • Item external ID + Language ID: <base_URL>/items/external-id/<content_item_external_id>/variants/<language_id>
  • Item external ID + Language codename: <base_URL>/items/external-id/<content_item_external_id>/variants/codename/<language_codename>

These endpoints accept GET, PUT, and DELETE requests, allowing you to retrieve, upsert, and delete language variants. You can mix and match the identifiers of content items and languages when requesting language variants.

Language variant object

When copying or migrating variants, you can take the variant object returned when retrieving a variant and use it as-is to upsert a variant.

Localized variant of a content item.

required
Array of Asset element (object) or Custom element (object) or Date & time element (object) or Linked items element (object) or Multiple choice element (object) or Number element (object) or Rich text element (object) or SubpagesElement (object) or Taxonomy element (object) or Text element (object) or URL slug element (object) unique

List of elements as defined in the item's content type.

object

Specifies the variant's current workflow and workflow step.

object
Deprecated

Reference to the variant's current workflow step.

object

Reference to the content item.

object

Reference to the language of the variant.

The default language will always have the ID of 00000000-0000-0000-0000-000000000000.

last_modified
string <date-time>

ISO-8601 formatted date and time of the last change of content.

object

Specifies the variant's scheduled publishing and unpublishing information.

object

Specifies the variant's due date information.

{
  • "elements": [
    • {
      • "element": {
        • "id": "c7c3b834-2222-5677-89c4-b46f04489109"
        },
      • "value": "Text element value"
      },
    • {
      • "mode": "custom",
      • "element": {
        • "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
        },
      • "value": "custom-url-slug-value"
      }
    ],
  • "workflow": {
    • "workflow_identifier": {
      • "id": "06ea628e-4ec7-4991-91e4-1412995151ee"
      },
    • "step_identifier": {
      • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
      }
    },
  • "workflow_step": {
    • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
    },
  • "item": {
    • "id": "82ef61f4-ccee-42ac-95e2-1a44beda9625"
    },
  • "language": {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "last_modified": "2020-02-27T19:08:25.404Z",
  • "schedule": {
    • "publish_time": "2024-03-31T08:00:00",
    • "publish_display_timezone": "Europe/Prague",
    • "unpublish_time": "2024-04-30T08:00:00",
    • "unpublish_display_timezone": "Europe/Prague"
    },
  • "due_date": {
    • "value": "2024-02-26T06:04:00.7069564Z"
    }
}

Retrieve the latest language variant

get/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}

Retrieve the latest available version of the specified language variant of a content item. You can also explicitly retrieve the latest published version of the variant.

When retrieving variants, the API returns their latest versions. For example, if the variant contains both the draft and published versions, the API returns the draft version because it's considered the latest.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Responses
200

Language variant for the specified language and content item.

404

The specified language variant was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.viewLanguageVariant()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .byLanguageId('d1f95fde-af02-b3b5-bd9e-f232311ccab8')
  // .byLanguageCodename('es-ES')
  .toPromise();
Response samples
application/json
{
  • "elements": [
    • {
      • "element": {
        • "id": "c7c3b834-2222-5677-89c4-b46f04489109"
        },
      • "value": "Text element value"
      },
    • {
      • "mode": "custom",
      • "element": {
        • "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
        },
      • "value": "custom-url-slug-value"
      }
    ],
  • "workflow": {
    • "workflow_identifier": {
      • "id": "06ea628e-4ec7-4991-91e4-1412995151ee"
      },
    • "step_identifier": {
      • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
      }
    },
  • "workflow_step": {
    • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
    },
  • "item": {
    • "id": "82ef61f4-ccee-42ac-95e2-1a44beda9625"
    },
  • "language": {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "last_modified": "2020-02-27T19:08:25.404Z",
  • "schedule": {
    • "publish_time": "2024-03-31T08:00:00",
    • "publish_display_timezone": "Europe/Prague",
    • "unpublish_time": "2024-04-30T08:00:00",
    • "unpublish_display_timezone": "Europe/Prague"
    },
  • "due_date": {
    • "value": "2024-02-26T06:04:00.7069564Z"
    }
}

Upsert a language variant

put/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}

Add content to a language variant in an active language or update an existing language variant. You cannot update an existing language variant if its workflow step is set to Archived, Published, or Scheduled.

When creating a new variant:

When updating an existing variant, only the elements specified in the request body will be modified.

When copying variants, you can take the variant object returned by a GET request and use it as-is in the body of this request. If you need to migrate variants to another environment or project, see how to import content items.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Request Body schema: application/json
required

Specifies which elements to update. Each content element is represented as a key-value pair.

The element values can be strings, numbers, or Reference objects, depending on the element type.

required
Array of Asset element (object) or Custom element (object) or Date & time element (object) or Linked items element (object) or Multiple choice element (object) or Number element (object) or Rich text element (object) or SubpagesElement (object) or Taxonomy element (object) or Text element (object) or URL slug element (object) unique

List of elements as defined in the item's content type.

object

Specifies the variant's current workflow and workflow step.

object

Specifies the variant's due date information.

Responses
200

The updated language variant.

201

The created language variant.

400

The provided request body does not match the content type.

404

The specified content item or language does not exist.

Request samples
application/json
{
  • "elements": [
    • {
      • "element": {
        • "codename": "multiple_choice_element"
        },
      • "value": [
        • {
          }
        ]
      },
    • {
      • "element": {
        • "codename": "url_slug_element"
        },
      • "mode": "autogenerated"
      },
    • {
      • "element": {
        • "codename": "linked_items_element"
        },
      • "value": [
        • {
          }
        ]
      },
    • {
      • "element": {
        • "codename": "text_element"
        },
      • "value": "A tiny little plaintext."
      }
    ],
  • "due_date": {
    • "value": "2024-02-26T06:04:00.7069564Z"
    },
  • "workflow": {
    • "workflow_identifier": {
      • "id": "06ea628e-4ec7-4991-91e4-1412995151ee"
      },
    • "step_identifier": {
      • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
      }
    }
}
Response samples
application/json
{
  • "elements": [
    • {
      • "element": {
        • "id": "108ed7c0-fc8c-c0ec-d0b5-5a8071408b54"
        },
      • "value": [
        • {
          }
        ]
      },
    • {
      • "element": {
        • "id": "f2ff5e3f-a9ca-4604-58b0-34a2ad6a7cf1"
        },
      • "mode": "autogenerated",
      • "value": "my-articles-title"
      },
    • {
      • "element": {
        • "id": "63793ba4-6004-a93c-68ca-52a1f0482bca"
        },
      • "value": [
        • {
          },
        • {
          }
        ]
      },
    • {
      • "element": {
        • "id": "68f65095-c9b4-05d6-a473-2883c2f0c7af"
        },
      • "value": "A tiny little plaintext."
      }
    ],
  • "due_date": {
    • "value": "2024-02-26T06:04:00.7069564Z"
    },
  • "schedule": {
    • "publish_time": "2024-03-31T08:00:00",
    • "publish_display_timezone": "Europe/Prague",
    • "unpublish_time": "2024-04-30T08:00:00",
    • "unpublish_display_timezone": "Europe/Prague"
    },
  • "workflow": {
    • "workflow_identifier": {
      • "id": "06ea628e-4ec7-4991-91e4-1412995151ee"
      },
    • "step_identifier": {
      • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
      }
    },
  • "workflow_step": {
    • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
    },
  • "item": {
    • "id": "f4b3fc05-e988-4dae-9ac1-a94aba566474"
    },
  • "language": {
    • "id": "d1f95fde-af02-b3b5-bd9e-f232311ccab8"
    },
  • "last_modified": "2020-11-21T09:08:33.2229841Z"
}

Delete a language variant

delete/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}

Deletes a specific language variant. If you want to delete all language variants of a content item, see how to Delete a content item.

When you delete the last variant of a content item, the whole content item is deleted.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Responses
204

The specified language variant was deleted.

404

The specified language variant was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteLanguageVariant()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .byLanguageId('d1f95fde-af02-b3b5-bd9e-f232311ccab8')
  // .byLanguageCodename('es-ES')
  .toPromise();
Response samples
application/json
{
  • "request_id": "00000000-0000-0000-c813-0080000000c3",
  • "error_code": 103,
  • "message": "The requested content item variant was not found."
}

Retrieve the published language variant

get/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}/published

Retrieve the currently published version of the specified language variant of a content item. You can also retrieve the latest available version of the variant.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Responses
200

The currently published language variant of the specified content item.

404

The specified variant doesn't have a published version.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var identifier = new LanguageVariantIdentifier(Reference.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474")), Reference.ById(Guid.Parse("d1f95fde-af02-b3b5-bd9e-f232311ccab8")));
// var identifier = new LanguageVariantIdentifier(Reference.ById(Guid.Parse("f4b3fc05-e988-4dae-9ac1-a94aba566474")), Reference.ByCodename("es-ES"));
// var identifier = new LanguageVariantIdentifier(Reference.ByCodename("on_roasts"), Reference.ById(Guid.Parse("d1f95fde-af02-b3b5-bd9e-f232311ccab8")));
// var identifier = new LanguageVariantIdentifier(Reference.ByCodename("on_roasts"), Reference.ByCodename("es-ES"));
// var identifier = new LanguageVariantIdentifier(Reference.ByExternalId("59713"), Reference.ById(Guid.Parse("d1f95fde-af02-b3b5-bd9e-f232311ccab8")));
// var identifier = new LanguageVariantIdentifier(Reference.ByExternalId("59713"), Reference.ByCodename("es-ES"));

var response = await client.GetPublishedLanguageVariantAsync(identifier);
Response samples
application/json
{
  • "elements": [
    • {
      • "element": {
        • "id": "c7c3b834-2222-5677-89c4-b46f04489109"
        },
      • "value": "Text element value"
      },
    • {
      • "mode": "custom",
      • "element": {
        • "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
        },
      • "value": "custom-url-slug-value"
      }
    ],
  • "workflow": {
    • "workflow_identifier": {
      • "id": "06ea628e-4ec7-4991-91e4-1412995151ee"
      },
    • "step_identifier": {
      • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
      }
    },
  • "workflow_step": {
    • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
    },
  • "item": {
    • "id": "82ef61f4-ccee-42ac-95e2-1a44beda9625"
    },
  • "language": {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "last_modified": "2020-02-27T19:08:25.404Z",
  • "schedule": {
    • "publish_time": "2024-03-31T08:00:00",
    • "publish_display_timezone": "Europe/Prague",
    • "unpublish_time": "2024-04-30T08:00:00",
    • "unpublish_display_timezone": "Europe/Prague"
    },
  • "due_date": {
    • "value": "2024-02-26T06:04:00.7069564Z"
    }
}

Retrieve language variants of an item

get/projects/{environment_id}/items/{item_identifier}/variants

Retrieve a list of language variants of a content item.

When retrieving variants, the API returns their latest versions. For example, if the variant contains both the draft and published versions, the API returns the draft version because it's considered the latest.

If you want to retrieve metadata information about the parent content item, see how to Retrieve a content item.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
Responses
200

Array of language variants for the specified content item.

404

The specified content item was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.listLanguageVariantsOfItem()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .toPromise();
Response samples
application/json
[
  • {
    • "elements": [
      • {
        • "element": {
          },
        • "value": "Text element value"
        },
      • {
        • "mode": "custom",
        • "element": {
          },
        • "value": "custom-url-slug-value"
        }
      ],
    • "workflow": {
      • "workflow_identifier": {
        • "id": "06ea628e-4ec7-4991-91e4-1412995151ee"
        },
      • "step_identifier": {
        • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
        }
      },
    • "workflow_step": {
      • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
      },
    • "item": {
      • "id": "82ef61f4-ccee-42ac-95e2-1a44beda9625"
      },
    • "language": {
      • "id": "00000000-0000-0000-0000-000000000000"
      },
    • "last_modified": "2020-02-27T19:08:25.404Z",
    • "schedule": {
      • "publish_time": "2024-03-31T08:00:00",
      • "publish_display_timezone": "Europe/Prague",
      • "unpublish_time": "2024-04-30T08:00:00",
      • "unpublish_display_timezone": "Europe/Prague"
      },
    • "due_date": {
      • "value": "2024-02-26T06:04:00.7069564Z"
      }
    }
]

List language variants by type

get/projects/{environment_id}/types/{type_identifier}/variants

Retrieve a dynamically paginated list of language variants for a specified content type.

When retrieving variants, the API returns their latest versions. For example, if the variant contains both the draft and published versions, the API returns the draft version because it's considered the latest.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
type_identifier
required
string

Identifies the content type by internal ID (e.g., 269202ad-1d9d-47fd-b3e8-bdb05b3e3cf0), external ID (e.g., external-id/Content-Type-123), or codename (e.g., codename/hosted_video).

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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of language variants based on the specified content type.

400

The specified continuation token is incorrect.

404

The specified content type was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listLanguageVariantsOfContentType()
  .byTypeCodename('article')
  .toPromise();

// Gets all pages of results
// const response = await client.listLanguageVariantsOfContentType()
//   .byTypeCodename('article')
//   .toAllPromise();
Response samples
application/json
{
  • "variants": [
    • {
      • "elements": [
        • {
          },
        • {
          }
        ],
      • "workflow": {
        • "workflow_identifier": {
          },
        • "step_identifier": {
          }
        },
      • "workflow_step": {
        • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
        },
      • "item": {
        • "id": "82ef61f4-ccee-42ac-95e2-1a44beda9625"
        },
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000"
        },
      • "last_modified": "2020-02-27T19:08:25.404Z",
      • "schedule": {
        • "publish_time": "2024-03-31T08:00:00",
        • "publish_display_timezone": "Europe/Prague",
        • "unpublish_time": "2024-04-30T08:00:00",
        • "unpublish_display_timezone": "Europe/Prague"
        },
      • "due_date": {
        • "value": "2024-02-26T06:04:00.7069564Z"
        }
      }
    ],
  • "pagination": {}
}

List language variants containing components by type

get/projects/{environment_id}/types/{type_identifier}/components

Retrieve a dynamically paginated list of language variants that contain components specified by a content type.

The returned language variants may be based on any content type as long as the variants contain at least one component of the specified type. You may want to get language variants with specific components when migrating content based on a specific content type.

When retrieving variants, the API returns their latest versions. For example, if the variant contains both the draft and published versions, the API returns the draft version because it's considered the latest.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
type_identifier
required
string

Identifies the content type by internal ID (e.g., 269202ad-1d9d-47fd-b3e8-bdb05b3e3cf0), external ID (e.g., external-id/Content-Type-123), or codename (e.g., codename/hosted_video).

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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of language variants that contain components based on the specified content type.

400

The specified continuation token is incorrect.

404

The specified content type was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listLanguageVariantsOfContentTypeWithComponents()
  .byTypeID('6434e475-5a29-4866-9fd1-6d1ca873f5be')
//   .byTypeCodename('article')
  .toPromise();

// Gets all pages of results
// const response = await client.listLanguageVariantsOfContentTypeWithComponents()
//   .byTypeCodename('article')
//   .toAllPromise();
Response samples
application/json
{
  • "variants": [
    • {
      • "elements": [
        • {
          },
        • {
          }
        ],
      • "workflow": {
        • "workflow_identifier": {
          },
        • "step_identifier": {
          }
        },
      • "workflow_step": {
        • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
        },
      • "item": {
        • "id": "82ef61f4-ccee-42ac-95e2-1a44beda9625"
        },
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000"
        },
      • "last_modified": "2020-02-27T19:08:25.404Z",
      • "schedule": {
        • "publish_time": "2024-03-31T08:00:00",
        • "publish_display_timezone": "Europe/Prague",
        • "unpublish_time": "2024-04-30T08:00:00",
        • "unpublish_display_timezone": "Europe/Prague"
        },
      • "due_date": {
        • "value": "2024-02-26T06:04:00.7069564Z"
        }
      }
    ],
  • "pagination": {}
}

List language variants by collection

get/projects/{environment_id}/collections/{collection_identifier}/variants

Retrieve a dynamically paginated list of language variants for a specified collection.

When retrieving variants, the API returns their latest versions. For example, if the variant contains both the draft and published versions, the API returns the draft version because it's considered the latest.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
collection_identifier
required
string

Identifies the content collection by its internal ID (e.g., b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89), codename (e.g., codename/global_collection), or external ID (e.g., external-id/my-collection-id).

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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of language variants that belong to the specified collection.

400

The specified continuation token is incorrect.

404

The specified collection was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
    environmentId: '<YOUR_ENVIRONMENT_ID>',
    apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listLanguageVariantsByCollection()
    .byCollectionCodename('important_collection')
    .toPromise();

// Gets all pages of results
// const response = await client.listLanguageVariantsByCollection()
//     .byCollectionCodename('important_collection')
//     .toAllPromise();
Response samples
application/json
{
  • "variants": [
    • {
      • "elements": [
        • {
          },
        • {
          }
        ],
      • "workflow": {
        • "workflow_identifier": {
          },
        • "step_identifier": {
          }
        },
      • "workflow_step": {
        • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
        },
      • "item": {
        • "id": "82ef61f4-ccee-42ac-95e2-1a44beda9625"
        },
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000"
        },
      • "last_modified": "2020-02-27T19:08:25.404Z",
      • "schedule": {
        • "publish_time": "2024-03-31T08:00:00",
        • "publish_display_timezone": "Europe/Prague",
        • "unpublish_time": "2024-04-30T08:00:00",
        • "unpublish_display_timezone": "Europe/Prague"
        },
      • "due_date": {
        • "value": "2024-02-26T06:04:00.7069564Z"
        }
      }
    ],
  • "pagination": {}
}

List language variants by space

get/projects/{environment_id}/spaces/{space_identifier}/variants

Retrieve a dynamically paginated list of language variants for a specified space.

Language variants are not directly connected to spaces. Rather, the parent content item of each language variant is assigned to a specific collection. Each collection can be linked to zero, one, or more spaces.

When retrieving variants, the API returns their latest versions. For example, if the variant contains both the draft and published versions, the API returns the draft version because it's considered the latest.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
space_identifier
required
string

Identifies a space by it's internal ID (eg., 6291c693-f6e4-4a6b-ac67-5c31c32f9388) or codename (eg., codename/space_1)

Example: 6291c693-f6e4-4a6b-ac67-5c31c32f9388
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of language variants that belong to the specified space.

400

The specified continuation token is incorrect.

404

The specified space was not found.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var identifier = Reference.ById(Guid.Parse("6291c693-f6e4-4a6b-ac67-5c31c32f9388"));
// var identifier = Reference.ByCodename("space_1");

// Gets the first page of results
var response = await client.ListLanguageVariantsBySpaceAsync(identifier);
Response samples
application/json
{
  • "variants": [
    • {
      • "elements": [
        • {
          },
        • {
          }
        ],
      • "workflow": {
        • "workflow_identifier": {
          },
        • "step_identifier": {
          }
        },
      • "workflow_step": {
        • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
        },
      • "item": {
        • "id": "82ef61f4-ccee-42ac-95e2-1a44beda9625"
        },
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000"
        },
      • "last_modified": "2020-02-27T19:08:25.404Z",
      • "schedule": {
        • "publish_time": "2024-03-31T08:00:00",
        • "publish_display_timezone": "Europe/Prague",
        • "unpublish_time": "2024-04-30T08:00:00",
        • "unpublish_display_timezone": "Europe/Prague"
        },
      • "due_date": {
        • "value": "2024-02-26T06:04:00.7069564Z"
        }
      }
    ],
  • "pagination": {}
}

Create a new version of a language variant

put/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}/new-version

Create a new version of a published language variant while keeping the original version published and available via Delivery API. This is the same as creating new versions in the UI.

You can only create new versions of published language variants that don't already have an existing Draft (unpublished) version.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
Responses
204

A new version of the specified published language variant was created.

400

The specified language variant is not published.

404

The specified language variant was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.createNewVersionOfLanguageVariant()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .byLanguageId('d1f95fde-af02-b3b5-bd9e-f232311ccab8')
  // .byLanguageCodename('es-ES')
  .toPromise();
Response samples
application/json
{
  • "request_id": "550c4c30-1b9c-4fe4-8140-a9cda5cd7c11",
  • "error_code": 214,
  • "message": "Cannot create a new version of a language variant that is not published."
}

Change the workflow of a language variant

put/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}/change-workflow

Move the specified variant to the specified workflow and workflow step. This is the same as updating the workflow in the UI.

The API follows the workflow transition limitations present in the UI. This means you can change the workflow step of the language variant only to the workflow steps you have permissions to.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Request Body schema: application/json

Specify the workflow and workflow step to move the variant.

required
object

Reference to the content item variant's workflow.

required
object

Reference to the content item variant's workflow step.

Responses
204

The variant was moved to the specified workflow step in the specified workflow.

400

The specified workflow operation is invalid.

404

The specified language variant was not found.

Request samples
application/json
{
  • "workflow_identifier": {
    • "id": "06ea628e-4ec7-4991-91e4-1412995151ee"
    },
  • "step_identifier": {
    • "id": "dc87d7cf-424b-4b89-9519-c9f79a3458b7"
    }
}
Response samples
application/json
{
  • "request_id": "385bc5fe-cc64-4924-bee1-78f271d4bbc5",
  • "error_code": 215,
  • "message": "Cannot change workflow step to Published. If you want to publish a language variant via the Management API, use the '/publish' endpoint instead."
}

Change the workflow step of a language variantDeprecated

put/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}/workflow/{workflow_step_identifier}

Use a new endpoint

This endpoint has been deprecated in favor of a new endpoint that supports multiple workflows.

Move the specified language variant to the specified workflow step in the default workflow.

The API follows the workflow transition limitations present in the UI. This means you can change the workflow step of the language variant only to the workflow steps you have permissions to.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
workflow_step_identifier
required
string

Identifies the workflow step by its internal ID (e.g., 13145328-b946-4e47-9c9d-6f40c7aaeaef) or codename (e.g., codename/draft).

Example: draft
Responses
204

The workflow step of the specified language variant was updated.

400

The specified workflow operation is invalid.

404

The specified language variant was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.changeWorkflowStepOfLanguageVariant()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .byLanguageId('d1f95fde-af02-b3b5-bd9e-f232311ccab8')
  // .byLanguageCodename('es-ES')
  .byWorkflowStepId('16221cc2-bd22-4414-a513-f3e555c0fc93')
  .toPromise();
Response samples
application/json
{
  • "request_id": "385bc5fe-cc64-4924-bee1-78f271d4bbc5",
  • "error_code": 215,
  • "message": "Cannot change workflow step to Published. If you want to publish a language variant via the Management API, use the '/publish' endpoint instead."
}

Languages

Languages let you create localized content. Your content items can contain as many language variants as there are active languages in your environment.

Language object

id
string

The language's internal ID.

The ID of the default language is always 00000000-0000-0000-0000-000000000000.

name
required
string <= 25 characters

The language's display name.

codename
required
string <= 25 characters

The language's codename. Initially generated from the language's name unless you add the language via API.

external_id
string

External ID of the language. Only present if defined when creating the language.

is_active
boolean

Determines whether the language is active.

is_default
boolean

Determines whether the language is default.

object

Language to use when the current language contains no content. With multiple languages you can create fallback chains.

{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "name": "Default language",
  • "codename": "default",
  • "external_id": "string",
  • "is_active": "true",
  • "is_default": "true",
  • "fallback_language": {
    • "id": "00000000-0000-0000-0000-000000000000"
    }
}

Add a language

post/projects/{environment_id}/languages

Create new languages in your environment. For each active language, you can create localized content using language variants.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

The language to be added.

name
required
string <= 25 characters

The language's display name.

codename
required
string <= 25 characters

The language's codename. Initially generated from the language's name unless you add the language via API.

external_id
string

External ID of the language. Only present if defined when creating the language.

is_active
boolean

Determines whether the language is active.

object

Language to use when the current language contains no content. With multiple languages you can create fallback chains.

Responses
201

The created language object.

400

The specified request body is invalid or the language already exists.

Request samples
application/json
{
  • "name": "German (Germany)",
  • "codename": "de-DE",
  • "is_active": true,
  • "fallback_language": {
    • "codename": "default"
    },
  • "external_id": "standard-german"
}
Response samples
application/json
{
  • "id": "2ea66788-d3b8-5ff5-b37e-258502e4fd5d",
  • "name": "German (Germany)",
  • "codename": "de-DE",
  • "external_id": "standard-german",
  • "is_active": true,
  • "is_default": false,
  • "fallback_language": {
    • "id": "00000000-0000-0000-0000-000000000000"
    }
}

List languages

get/projects/{environment_id}/languages

Retrieve a dynamically paginated list of languages from your environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of languages.

400

The specified continuation token is incorrect.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listLanguages()
  .toPromise();

// Gets all pages of results
// const response = await client.listLanguages()
//   .toAllPromise();
Response samples
application/json
{
  • "languages": [
    • {
      • "id": "00000000-0000-0000-0000-000000000000",
      • "name": "Default language",
      • "codename": "default",
      • "external_id": "string",
      • "is_active": "true",
      • "is_default": "true",
      • "fallback_language": {
        • "id": "00000000-0000-0000-0000-000000000000"
        }
      }
    ],
  • "pagination": {}
}

Retrieve a language

get/projects/{environment_id}/languages/{language_identifier}

Retrieve a language from your environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
language_identifier
required
string

Identifies the language by its internal ID (e.g., 2ea66788-d3b8-5ff5-b37e-258502e4fd5d), external ID (e.g., external-id/standard-german), or codename (e.g., codename/de-DE).

Responses
200

A single language object.

404

The specified language was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.viewLanguage()
  .byLanguageId('2ea66788-d3b8-5ff5-b37e-258502e4fd5d')
  // .byLanguageCodename('de-DE')
  // .byExternalId('standard-german')
  .toPromise();
Response samples
application/json
{
  • "id": "00000000-0000-0000-0000-000000000000",
  • "name": "Default language",
  • "codename": "default",
  • "external_id": "string",
  • "is_active": "true",
  • "is_default": "true",
  • "fallback_language": {
    • "id": "00000000-0000-0000-0000-000000000000"
    }
}

Modify a language

patch/projects/{environment_id}/languages/{language_identifier}

Modify languages in your environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
language_identifier
required
string

Identifies the language by its internal ID (e.g., 2ea66788-d3b8-5ff5-b37e-258502e4fd5d), external ID (e.g., external-id/standard-german), or codename (e.g., codename/de-DE).

Request Body schema: application/json
required

Specifies the operations to perform on the existing languages.

Array (non-empty)
op
required
string

The operation to perform.

Allowed value Description
replace

Specifies the replace operation.

property_name
required
string

The name of the language property that you want to modify.

  • Use name to change the display name of the language.
  • Use codename to change the language codename.
  • Use fallback_language to change the fallback language for the specified language.
  • Use is_active to determine whether the language will be set as active.
required
String (string) or Reference (object) or Boolean (boolean)

The value or object to insert in the specified property. The format of the value property depends on value of the property_name property.

  • For property_name of name or codename, the value property is string.
  • For property_name of fallback_language, the value property is a Reference object.
  • For property_name of is_active, the value property is boolean.
Responses
200

The modified language object.

400

The specified set of operations is invalid.

404

The specified language was not found.

Request samples
application/json
[
  • {
    • "op": "replace",
    • "property_name": "fallback_language",
    • "value": {
      • "codename": "default"
      }
    },
  • {
    • "op": "replace",
    • "property_name": "name",
    • "value": "Deutsch"
    }
]
Response samples
application/json
{
  • "id": "2ea66788-d3b8-5ff5-b37e-258502e4fd5d",
  • "name": "Deutsch",
  • "codename": "de-DE",
  • "external_id": "standard-german",
  • "is_active": true,
  • "is_default": false,
  • "fallback_language": {
    • "id": "00000000-0000-0000-0000-000000000000"
    }
}

Preview URLs

Configure preview URLs for each your content types. Every preview URL combines a space domain and a URL pattern.

Preview configuration object

Specifies how preview is set up in a given environment. This means the definitions of space domains and preview URLs for specific content types.

required
Array of objects unique

The space domains configured in your environment.

required
Array of objects unique

List of preview URLs, that is a combination of a space and URL pattern, for specific content types.

{
  • "space_domains": [
    • {
      • "space": {
        • "id": "fb2c6c2b-fb79-4d1b-856a-b59762e304b0"
        },
      • "domain": "www.mysite1.com"
      },
    • {
      • "space": {
        • "id": "24dace50-3cf6-4378-8704-453af9cdb60c"
        },
      • "domain": "www.mysite2.com"
      }
    ],
  • "preview_url_patterns": []
}

Retrieve preview configuration

get/projects/{environment_id}/preview-configuration

View the complete preview URLs configuration for the specified environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

The complete preview URLs configuration for the specified environment.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var response = await client.GetPreviewConfigurationAsync()
Response samples
application/json
{
  • "space_domains": [
    • {
      • "space": {
        • "id": "fb2c6c2b-fb79-4d1b-856a-b59762e304b0"
        },
      • "domain": "www.mysite1.com"
      },
    • {
      • "space": {
        • "id": "24dace50-3cf6-4378-8704-453af9cdb60c"
        },
      • "domain": "www.mysite2.com"
      }
    ],
  • "preview_url_patterns": []
}

Modify preview configuration

put/projects/{environment_id}/preview-configuration

Adjust the preview URLs configured for your environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

The preview configuration you want to use.

required
Array of objects unique

The space domains configured in your environment.

required
Array of objects unique

List of preview URLs, that is a combination of a space and URL pattern, for specific content types.

Responses
200

The modified preview configuration.

Request samples
application/json
{
  • "space_domains": [
    • {
      • "space": {
        • "id": "fb2c6c2b-fb79-4d1b-856a-b59762e304b0"
        },
      • "domain": "www.mysite1.com"
      },
    • {
      • "space": {
        • "id": "24dace50-3cf6-4378-8704-453af9cdb60c"
        },
      • "domain": "www.mysite2.com"
      }
    ],
  • "preview_url_patterns": []
}
Response samples
application/json
{
  • "space_domains": [
    • {
      • "space": {
        • "id": "fb2c6c2b-fb79-4d1b-856a-b59762e304b0"
        },
      • "domain": "www.mysite1.com"
      },
    • {
      • "space": {
        • "id": "24dace50-3cf6-4378-8704-453af9cdb60c"
        },
      • "domain": "www.mysite2.com"
      }
    ],
  • "preview_url_patterns": []
}

Publishing

The API follows the workflow transition limitations present in the UI. You can publish or schedule a variant only if you have the permission to move it to the workflow step.

Publish or schedule a language variant

put/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}/publish

Change the workflow step of the specified language variant to "Published" or schedule publishing at the specified time.

  • Equivalent to the UI operations of publishing and scheduling content.
  • The API follows the workflow transition limitations present in the UI. This means you can publish or schedule the variant only if the workflow allows you to move the variant from the current workflow step to scheduled or published.
  • Scheduling a published language variant has no effect.
SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Request Body schema: application/json
scheduled_to
string <date-time>

ISO-8601 formatted date-time for scheduled publishing.

If omitted, the specified variant is published immediately.

display_timezone
string

IANA time zone name used to display the time offset of the scheduled publish date in the UI.

The time zone doesn't modify the scheduled publish date specified in the scheduled_to property.

If omitted, the scheduled publish date is displayed in a local time zone.

Obsolete values: "America/Ojinaga", "Asia/Qyzylorda", "Europe/Kiev".

Allowed values: "Africa/Abidjan" "Africa/Accra" "Africa/Addis_Ababa" … 319 more
Responses
204

The specified language variant was published or scheduled.

400

Selected schedule publish date is in the past

404

The specified language variant was not found.

Request samples
application/json
{
  • "scheduled_to": "2038-01-19T04:14:08",
  • "display_timezone": "Australia/Sydney"
}
Response samples
application/json
{
  • "request_id": "bf6cc72a3efc514d",
  • "error_code": 5,
  • "message": "The provided request body is invalid. See 'validation_errors' for more information and specify a valid JSON object.",
  • "validation_errors": [
    • {
      • "message": "The provided date-time value needs to be in the future.",
      • "path": "scheduled_to"
      }
    ]
}

Cancel scheduled publishing of a language variant

put/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}/cancel-scheduled-publish

Cancel scheduling of a language variant.

Equivalent to canceling scheduled content in the UI. If the specified language variant is not scheduled, its workflow step is not changed.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Responses
204

Scheduled publishing was canceled and the variant moved to the first workflow step.

400

The specified language variant was not scheduled.

404

The specified language variant was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.cancelSheduledPublishingOfLanguageVariant()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .byLanguageId('d1f95fde-af02-b3b5-bd9e-f232311ccab8')
  // .byLanguageCodename('es-ES')
  .toPromise();
Response samples
application/json
{
  • "request_id": "|f027690dca4a294a954f54378e68fa12.d197c75_",
  • "error_code": 218,
  • "message": "Cannot cancel scheduling of a language variant that is not scheduled to publish."
}

Unpublish or schedule unpublishing of a language variant

put/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}/unpublish-and-archive

Unpublish the specified language variant and change its workflow step to "Archived" or schedule these operations.

  • Equivalent to the UI operations of unpublishing and adding an unpublish date.
  • You can unpublish only a published language variant.
  • You can schedule for unpublishing only variants that are published or scheduled for publishing.
SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Request Body schema: application/json
scheduled_to
string <date-time>

ISO-8601 formatted date-time for scheduled unpublishing.

If omitted, the specified variant is unpublished immediately.

display_timezone
string

IANA time zone name used to display the time offset of the scheduled unpublish date in the UI.

The time zone doesn't modify the schedule unpublish date specified in the scheduled_to property.

If omitted, the scheduled unpublish date will be displayed in a local time zone.

Obsolete values: "America/Ojinaga", "Asia/Qyzylorda", "Europe/Kiev".

Allowed values: "Africa/Abidjan" "Africa/Accra" "Africa/Addis_Ababa" … 319 more
Responses
204

The specified language variant was unpublished or scheduled for unpublishing.

400

The specified time zone is not a valid IANA time zone.

404

The specified language variant was not found.

Request samples
application/json
{
  • "scheduled_to": "2038-01-19T04:14:08",
  • "display_timezone": "Australia/Sydney"
}
Response samples
application/json
{
  • "request_id": "5ea183ec21712c08",
  • "error_code": 5,
  • "message": "The provided request body is invalid. See 'validation_errors' for more information and specify a valid JSON object.",
  • "validation_errors": [
    • {
      • "message": "Time zone name must be valid according to the IANA specification. See https://kontent.ai/learn/reference/management-api-v2 for details.",
      • "path": "display_timezone"
      }
    ]
}

Cancel scheduled unpublishing of a language variant

put/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}/cancel-scheduled-unpublish

Cancel scheduled unpublishing of the specified language variant.

  • The scheduled unpublishing date will be removed and the variant will no longer get unpublished automatically.
  • If the specified language variant isn't scheduled for unpublishing, it doesn't get changed.
SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Responses
204

Scheduled unpublishing was canceled.

400

The specified language variant was not scheduled for unpublishing.

404

The specified language variant was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.cancelSheduledUnpublishingOfLanguageVariant()
  // .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  .byItemCodename('my_article')
  // .byItemExternalId('59713')
  // .byLanguageId('d1f95fde-af02-b3b5-bd9e-f232311ccab8')
  .byLanguageCodename('es-mx')
  .toPromise();
Response samples
application/json
{
  • "request_id": "|f027690dca4a294a954f54378e68fa12.d197c75_",
  • "error_code": 218,
  • "message": "Nothing to cancel. The specified language variant is not scheduled for unpublishing."
}

Unpublish a language variantDeprecated

put/projects/{environment_id}/items/{item_identifier}/variants/{language_identifier}/unpublish

Use a new endpoint

This endpoint has been deprecated in favor of a new endpoint.

Unpublish a language variant to make it no longer accessible through the Delivery API.

  • The variant is moved to the Draft workflow step or to the first workflow step you have permissions for.
  • To also archive the language variant, use the Unpublish and archive a language variant endpoint.
  • You can unpublish only a published language variant.
SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
item_identifier
required
string

Identifies a content item by its internal ID (e.g., 335d17ac-b6ba-4c6a-ae31-23c1193215cb), external ID (e.g., external-id/custom-identifier-for-my-article), or codename (e.g., codename/my_article).

Example: 335d17ac-b6ba-4c6a-ae31-23c1193215cb
language_identifier
required
string

Identifies the language by its internal ID (e.g., d1f95fde-af02-b3b5-bd9e-f232311ccab8) or codename (e.g., codename/es-ES).

Example: d1f95fde-af02-b3b5-bd9e-f232311ccab8
Responses
204

The specified language variant was unpublished and moved to the first workflow step.

400

The specified language variant is not published.

404

The specified language variant was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.unpublishLanguageVariant()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .byLanguageId('d1f95fde-af02-b3b5-bd9e-f232311ccab8')
  // .byLanguageCodename('es-ES')
  .toPromise();
Response samples
application/json
{
  • "request_id": "5872650e-32bb-4e23-9d73-ba5139b93898",
  • "error_code": 213,
  • "message": "Cannot unpublish a language variant that is not published."
}

References

To identify specific objects in the environment, the API uses references to point to those objects.

Internally, the API uses references by internal ID to point to other objects. When you're adding or modifying objects using the API, you can also reference the objects by their codenames or external IDs, if present.

Reference object

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Reference to a specific object in the environment.

id
string <uuid>

The referenced object's internal ID.

codename
string

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id
string

The referenced object's external ID. The value of the external_id property must not contain the following characters: /, ., ;.

{
  • "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
}

How to specify an object reference

When specifying references to objects, the object can be identified by one of three properties:

  1. Internal ID such as 18b43cc5-f4fd-0172-842b-3ae2c878cf6f
    • Generated by the system automatically.
    • Unique per object type, such as content item, content type, and more.
    • Can be used to specify any object.
  2. Codename such as object_codename
    • Initially generated from the object's display name.
    • Unique per object type, such as content item, content type, and more.
    • Can be used to specify most objects.
  3. External ID such as custom-object-identifier
    • Specified manually when creating the object through the Management API. The external ID cannot be changed later.
    • Unique per object type. For example, the uniqueness applies to content types and their elements within an environment, content items within an environment, and so on. This means you can have a content type and an element with the same external ID, but no two elements can use the same external ID within an environment.
    • Can be used to specify custom identifiers for user-created objects such as assets, content items, content types, and more.

Rules for codenames

When editing codenames, the new codenames must meet the following conditions:

  • Only lowercase letters, numbers, and underscores are permitted.
  • Codenames must start with a letter or an underscore and have at least one character.
  • Codenames are usually limited to 60 characters, but longer codenames are allowed for multiple choice options and taxonomy terms.
  • Codenames of elements within a snippet must be prefixed with the snippet's codename.
  • Codenames must be unique per object type. This applies to, for example, every element within a content type, every content type within an environment, every content item within an environment, and so on.

This means the following applies when codenames are generated automatically:

  • All letters are made lowercase.
  • All forbidden characters are replaced by _.
  • For any names that start with a number, the codename will start with n.
  • Codenames that duplicate another codename will have a random string attached to the end.
  • Codenames of elements within a snippet will be prefixed with the snippet's codename.
  • Codenames will be cut off at the character limit.

External IDs for imported content

By using external IDs to reference other objects, you can import your content in the order you prefer.

For example, when importing multiple articles that contain images, you can reference these images with external IDs, such as roaster or coffee-cup, before uploading them. The referenced images will be visible in the UI only after you add them as assets via the API. With this approach, you can choose whether you want to create content items first and then upload binary files for assets, or vice versa.

This means you can use external IDs to reference objects that don't exist yet and add the objects via the API later. References to non-existent objects will be stored and retrieved via the API as internal IDs.

To check for any references to not-yet-created objects, we recommend you validate your content.

Referencing objects that don't exist yet

With Management API, you can reference non-existent objects in the following elements:

See how to import linked content to learn more.

Missing objects in the UI

If you use external IDs to reference non-existent objects in your elements, the referenced objects won't be shown in the UI. This is because the system cannot find those objects. The referenced assets, content items, and taxonomy terms will be displayed after you create them with their specific external IDs via the Management API.

To add the missing objects, see:

Roles

Roles define the permissions that you can assign to users in your project and its environments. Use roles to limit what your users can do.

The endpoints for retrieving roles require Enterprise plan and the Manage custom roles permission.

Role object

id
required
string <uuid>

The role's ID.

name
required
string

The role's display name.

codename
string

The role's codename. The codename property is only applicable for the Project manager role.

{
  • "id": "7dedb656-aef7-40ae-8158-98bbf3542f4a",
  • "name": "Project manager",
  • "codename": "project-manager"
}

List roles

get/projects/{environment_id}/roles

Retrieve a list of all roles in the specified environment.

This endpoint requires Enterprise plan and the Manage custom roles permission.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

All roles in the environment.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var response = await client.ListProjectRolesAsync();
Response samples
application/json
{
  • "roles": [
    • {
      • "id": "7dedb656-aef7-40ae-8158-98bbf3542f4a",
      • "name": "Project manager",
      • "codename": "project-manager"
      },
    • {
      • "id": "ee483b59-5a24-4010-b277-ae224c34bc71",
      • "name": "Custom role"
      }
    ]
}

Retrieve a role

get/projects/{environment_id}/roles/{role_identifier}

Retrieve information about a role.

This endpoint requires Enterprise plan and the Manage custom roles permission.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
role_identifier
required
string

Identifies the role by its internal ID (e.g., 7dedb656-aef7-40ae-8158-98bbf3542f4a), or codename (e.g., codename/project-manager).

Example: 7dedb656-aef7-40ae-8158-98bbf3542f4a
Responses
200

A single role object.

404

The specified role was not found.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var identifier = Reference.ById(Guid.Parse("a23d3727-3b16-4d94-9eb0-85225d29cfef"));
//var identifier = Reference.ByCodename("project-manager");

var response = await client.GetProjectRoleAsync(identifier);
Response samples
application/json
{
  • "id": "7dedb656-aef7-40ae-8158-98bbf3542f4a",
  • "name": "Project manager",
  • "codename": "project-manager"
}

Spaces

Spaces helps you provide a channel-specific context for your content. One space equals one website or a different channel like mobile.

Spaces object

id
string <uuid>

The space's internal ID.

name
string [ 1 .. 200 ] characters

The space's display name.

codename
string [ 1 .. 210 ] characters

The space's codename.

null or object
Array of objects >= 0 items unique

An array of references to collections that belong to the space.

{
  • "id": "6291c693-f6e4-4a6b-ac67-5c31c32f9388",
  • "name": "Space 1",
  • "codename": "space_1",
  • "web_spotlight_root_item": {
    • "id": "42dbbfbf-80dd-4d09-8f4b-650f3ce7d4fb"
    },
  • "collections": [
    • {
      • "id": "511d4c6e-ff91-453e-9850-774867780ea3"
      },
    • {
      • "id": "faa44123-a826-4d78-9d2d-2fde10fb0d56"
      },
    • {
      • "id": "3c70b0cc-d9d8-4c9d-a01f-47a2d677fdd5"
      }
    ]
}

Add a space

post/projects/{environment_id}/spaces

Create a new space in your environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json

The space to be added.

name
string [ 1 .. 200 ] characters

The space's display name.

codename
string [ 1 .. 210 ] characters

The space's codename.

null or object
Array of objects >= 0 items unique

An array of references to collections that belong to the space.

Responses
201

The space was created.

400

The specified request body is invalid.

Request samples
application/json
{
  • "id": "6291c693-f6e4-4a6b-ac67-5c31c32f9388",
  • "name": "Space 1",
  • "codename": "space_1",
  • "web_spotlight_root_item": {
    • "id": "42dbbfbf-80dd-4d09-8f4b-650f3ce7d4fb"
    },
  • "collections": [
    • {
      • "id": "511d4c6e-ff91-453e-9850-774867780ea3"
      },
    • {
      • "id": "faa44123-a826-4d78-9d2d-2fde10fb0d56"
      },
    • {
      • "id": "3c70b0cc-d9d8-4c9d-a01f-47a2d677fdd5"
      }
    ]
}
Response samples
application/json
{
  • "id": "6291c693-f6e4-4a6b-ac67-5c31c32f9388",
  • "name": "Space 1",
  • "codename": "space_1",
  • "web_spotlight_root_item": {
    • "id": "42dbbfbf-80dd-4d09-8f4b-650f3ce7d4fb"
    },
  • "collections": [
    • {
      • "id": "511d4c6e-ff91-453e-9850-774867780ea3"
      },
    • {
      • "id": "faa44123-a826-4d78-9d2d-2fde10fb0d56"
      },
    • {
      • "id": "3c70b0cc-d9d8-4c9d-a01f-47a2d677fdd5"
      }
    ]
}

List spaces

get/projects/{environment_id}/spaces

Retrieve a list of spaces from your environment

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

A list of spaces.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client
  .listSpaces()
  .toPromise();
Response samples
application/json
[
  • {
    • "id": "6291c693-f6e4-4a6b-ac67-5c31c32f9388",
    • "name": "Space 1",
    • "codename": "space_1",
    • "web_spotlight_root_item": {
      • "id": "42dbbfbf-80dd-4d09-8f4b-650f3ce7d4fb"
      },
    • "collections": [
      • {
        • "id": "511d4c6e-ff91-453e-9850-774867780ea3"
        },
      • {
        • "id": "faa44123-a826-4d78-9d2d-2fde10fb0d56"
        },
      • {
        • "id": "3c70b0cc-d9d8-4c9d-a01f-47a2d677fdd5"
        }
      ]
    }
]

Retrieve a space

get/projects/{environment_id}/spaces/{space_identifier}

Retrieve a space from your environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
space_identifier
required
string

Identifies a space by it's internal ID (eg., 6291c693-f6e4-4a6b-ac67-5c31c32f9388) or codename (eg., codename/space_1)

Example: 6291c693-f6e4-4a6b-ac67-5c31c32f9388
Responses
200

A single space object.

404

The specified space was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client
  .viewSpace()
  .bySpaceCodename('my_new_space')
  .toPromise();
Response samples
application/json
{
  • "id": "6291c693-f6e4-4a6b-ac67-5c31c32f9388",
  • "name": "Space 1",
  • "codename": "space_1",
  • "web_spotlight_root_item": {
    • "id": "42dbbfbf-80dd-4d09-8f4b-650f3ce7d4fb"
    },
  • "collections": [
    • {
      • "id": "511d4c6e-ff91-453e-9850-774867780ea3"
      },
    • {
      • "id": "faa44123-a826-4d78-9d2d-2fde10fb0d56"
      },
    • {
      • "id": "3c70b0cc-d9d8-4c9d-a01f-47a2d677fdd5"
      }
    ]
}

Modify a space

patch/projects/{environment_id}/spaces/{space_identifier}

Modify a space in your environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
space_identifier
required
string

Identifies a space by it's internal ID (eg., 6291c693-f6e4-4a6b-ac67-5c31c32f9388) or codename (eg., codename/space_1)

Example: 6291c693-f6e4-4a6b-ac67-5c31c32f9388
Request Body schema: application/json
required

Specifies the operations to perform on the specified space.

Array (non-empty)
op
required
string

The operation to perform.

Allowed value Description
replace

Specifies the replace operation.

property_name
required
string

The space property that you want to modify, specified by its name.

Enum Value Description
name

Use to change the space's display name.

codename

Use to change the space's codename.

web_spotlight_root_item

Use to change the space's root item.

… 1 more
required
String (string) or Reference (object) or Array of Array of References (objects)

The value to insert into the specified property. The format of the value property depends on the value of the property_name property.

  • For property_name of name or codename, the value property is a string.
  • For property_name of web_spotlight_root_item, the value property is a Reference object.
  • For property_name of collections, the value property is an array of Reference objects.
Responses
200

The modified space object.

400

The specified set of operations is invalid.

Request samples
application/json
[
  • {
    • "op": "replace",
    • "property_name": "name",
    • "value": "New name"
    },
  • {
    • "op": "replace",
    • "property_name": "codename",
    • "value": "new_codename"
    },
  • {
    • "op": "replace",
    • "property_name": "collections",
    • "value": [
      • {
        • "codename": "us_branch"
        },
      • {
        • "id": "faa44123-a826-4d78-9d2d-2fde10fb0d56"
        }
      ]
    }
]
Response samples
application/json
{
  • "id": "6291c693-f6e4-4a6b-ac67-5c31c32f9388",
  • "name": "Space 1",
  • "codename": "space_1",
  • "web_spotlight_root_item": {
    • "id": "42dbbfbf-80dd-4d09-8f4b-650f3ce7d4fb"
    },
  • "collections": [
    • {
      • "id": "511d4c6e-ff91-453e-9850-774867780ea3"
      },
    • {
      • "id": "faa44123-a826-4d78-9d2d-2fde10fb0d56"
      },
    • {
      • "id": "3c70b0cc-d9d8-4c9d-a01f-47a2d677fdd5"
      }
    ]
}

Delete a space

delete/projects/{environment_id}/spaces/{space_identifier}

Delete a space from your environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
space_identifier
required
string

Identifies a space by it's internal ID (eg., 6291c693-f6e4-4a6b-ac67-5c31c32f9388) or codename (eg., codename/space_1)

Example: 6291c693-f6e4-4a6b-ac67-5c31c32f9388
Responses
204

The specified space was deleted.

404

The specified space was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client
  .deleteSpace()
  .bySpaceCodename('my_new_space')
  .toPromise();
Response samples
application/json
{
  • "request_id": "50e4b06809cbde0b",
  • "error_code": 121,
  • "message": "The requested space '{id: 6291c693-f6e4-4a6b-ac67-5c31c32f9388}' was not found."
}

Taxonomy groups

Taxonomies are a versatile tool for categorizing and organizing your content. Learn more about the use cases for taxonomies and see how to retrieve content tagged with a specific taxonomy term.

Taxonomy group object

The taxonomy group object contains all information about your taxonomy group, such as its metadata and a collection of its taxonomy terms.

codename
string [ 1 .. 60 ] characters

The taxonomy group's codename. Unless set while creating a taxonomy group, it is initially generated from the group's name and can later be modified.

external_id
string

The taxonomy group's external ID.

Only present if specified when creating the taxonomy group via API.

id
string <uuid>

The taxonomy group's internal ID.

last_modified
string <date-time>

ISO-8601 formatted date/time of the last change to the taxonomy group or its terms.

name
required
string [ 1 .. 50 ] characters

The taxonomy group's display name.

required
Array of objects

All terms in the taxonomy group.

The number of terms which can be set within a taxonomy group is limited to 1000.

{
  • "codename": "categories",
  • "external_id": "my-little-taxopony",
  • "id": "bef9dd62-a3b8-4146-83e4-33be707899b4",
  • "last_modified": "2020-11-14T14:05:43.9190528Z",
  • "name": "Categories",
  • "terms": [
    • {
      • "codename": "technology",
      • "external_id": "custom-term-identifier",
      • "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a",
      • "name": "Technology",
      • "terms": [ ]
      }
    ]
}

Add a taxonomy group

post/projects/{environment_id}/taxonomies

Create a new taxonomy group.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

The taxonomy group to add.

codename
string [ 1 .. 60 ] characters

The taxonomy group's codename. Unless set while creating a taxonomy group, it is initially generated from the group's name and can later be modified.

external_id
string

The taxonomy group's external ID.

Only present if specified when creating the taxonomy group via API.

name
required
string [ 1 .. 50 ] characters

The taxonomy group's display name.

required
Array of objects

All terms in the taxonomy group.

The number of terms which can be set within a taxonomy group is limited to 1000.

Responses
201

The added taxonomy group.

400

The specified request body is invalid or the taxonomy group already exists.

Request samples
application/json
{
  • "codename": "categories",
  • "external_id": "my-little-taxopony",
  • "name": "Categories",
  • "terms": [
    • {
      • "codename": "technology",
      • "external_id": "custom-term-identifier",
      • "name": "Technology",
      • "terms": [ ]
      }
    ]
}
Response samples
application/json
{
  • "codename": "categories",
  • "external_id": "my-little-taxopony",
  • "id": "bef9dd62-a3b8-4146-83e4-33be707899b4",
  • "last_modified": "2020-11-14T14:05:43.9190528Z",
  • "name": "Categories",
  • "terms": [
    • {
      • "codename": "technology",
      • "external_id": "custom-term-identifier",
      • "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a",
      • "name": "Technology",
      • "terms": [ ]
      }
    ]
}

List taxonomy groups

get/projects/{environment_id}/taxonomies

Retrieve a dynamically paginated list of taxonomy groups.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A list of taxonomy groups

400

The specified continuation token is incorrect.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

// Gets the first page of results
const response = await client.listTaxonomies()
  .toPromise();

// Gets all pages of results
// const response = await client.listTaxonomies()
//   .toAllPromise();
Response samples
application/json
{
  • "taxonomies": [
    • {
      • "codename": "categories",
      • "external_id": "my-little-taxopony",
      • "id": "bef9dd62-a3b8-4146-83e4-33be707899b4",
      • "last_modified": "2020-11-14T14:05:43.9190528Z",
      • "name": "Categories",
      • "terms": [
        • {
          }
        ]
      }
    ],
  • "pagination": {}
}

Retrieve a taxonomy group

get/projects/{environment_id}/taxonomies/{taxonomy_group_identifier}

Retrieve a taxonomy group.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
taxonomy_group_identifier
required
string

The identifier of a specific taxonomy group. You can specify a taxonomy group by its internal ID (e.g., 0be13600-e57c-577d-8108-c8d860330985), external ID (e.g., external-id/Tax-Group-123), or codename {e.g., codename/personas).

Responses
200

A single taxonomy group with metadata.

404

The specified taxonomy group was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.getTaxonomy()
  .byTaxonomyCodename("categories")
  // .byTaxonomyID("bef9dd62-a3b8-4146-83e4-33be707899b4")
  // .byTaxonomyExternalID("my-little-taxopony")
  .toPromise();
Response samples
application/json
{
  • "codename": "categories",
  • "external_id": "my-little-taxopony",
  • "id": "bef9dd62-a3b8-4146-83e4-33be707899b4",
  • "last_modified": "2020-11-14T14:05:43.9190528Z",
  • "name": "Categories",
  • "terms": [
    • {
      • "codename": "technology",
      • "external_id": "custom-term-identifier",
      • "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a",
      • "name": "Technology",
      • "terms": [ ]
      }
    ]
}

Modify a taxonomy group

patch/projects/{environment_id}/taxonomies/{taxonomy_group_identifier}

Modify how existing taxonomies are set up.

You can modify taxonomy groups and their taxonomy term configuration using the following operations:

  • addInto operation to add new objects. For example, add a taxonomy term to the taxonomy group.
  • move operation to reorder objects. For example, change the position of taxonomy terms.
  • remove operation to delete objects. For example, delete a taxonomy term from a taxonomy group.
  • replace operation to update values. For example, replace the value of a specific object property such as a codename.

To apply the operations on the taxonomy group's terms, you need to specify a path to the taxonomy term using a {path_reference}. Path references can use internal IDs, codenames, or external IDs.

  • id:5eb3d03e-c69d-4e93-b4cc-76f453271386
  • codename:my_text_element
  • external_id:id_from_external_source – Special characters such as slashes (/) need to be escaped. For example, to reference an object using its external ID of my/value, you use a path reference of external_id:my/value.
SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
taxonomy_group_identifier
required
string

The identifier of a specific taxonomy group. You can specify a taxonomy group by its internal ID (e.g., 0be13600-e57c-577d-8108-c8d860330985), external ID (e.g., external-id/Tax-Group-123), or codename {e.g., codename/personas).

Request Body schema: application/json
required

The operations to perform on the specified taxonomy group and its taxonomy terms.

Array
op
required
string

Specifies the operation to perform.

  • addInto to add new taxonomy terms
  • move to reorder taxonomy terms
  • remove to delete taxonomy terms
  • replace to modify taxonomy groups and their terms
object

Reference to an existing taxonomy term under which you want to add the new term.

If you need to add taxonomy terms to the root of the taxonomy group, don't specify a reference.

required
object

The taxonomy term object you want to add.

object

An optional reference to the taxonomy term after which you want to add the new taxonomy term.

For example, to add a term after an existing "Categories" term , you can set after to {codename: categories}.

The before and after properties are mutually exclusive.

object

An optional reference to the taxonomy term before which you want to add the new taxonomy term.

For example, to add a term before the existing "Categories" term, you can set before to {codename: categories}.

The before and after properties are mutually exclusive.

Responses
200

The modified taxonomy group.

400

One of the specified operations is invalid.

404

The specified taxonomy group was not found.

Request samples
application/json
[
  • {
    • "op": "replace",
    • "property_name": "name",
    • "value": "Categories"
    },
  • {
    • "op": "replace",
    • "property_name": "codename",
    • "value": "category"
    },
  • {
    • "op": "replace",
    • "reference": {
      • "codename": "first_term"
      },
    • "property_name": "terms",
    • "value": [
      • {
        • "name": "Second-level taxonomy term",
        • "codename": "second_term",
        • "terms": [
          ]
        }
      ]
    },
  • {
    • "op": "remove",
    • "reference": {
      • "external_id": "unused-taxonomy-term"
      }
    },
  • {
    • "op": "addInto",
    • "reference": {
      • "codename": "second_term"
      },
    • "value": {
      • "name": "New taxonomy term",
      • "external_id": "my-new-term",
      • "terms": [ ]
      }
    },
  • {
    • "op": "move",
    • "reference": {
      • "external_id": "my-new-term"
      },
    • "before": {
      • "codename": "first_term"
      }
    }
]
Response samples
application/json
{
  • "last_modified": "2019-04-02T08:08:40.3083064Z",
  • "id": "f30c7f72-e9ab-8832-2a57-62944a038809",
  • "name": "Categories",
  • "codename": "category",
  • "terms": [
    • {
      • "id": "146c5e35-dffe-5977-b943-16f0e862af2e",
      • "name": "New taxonomy term",
      • "codename": "new_taxonomy_term",
      • "external_id": "my-new-term",
      • "terms": [ ]
      },
    • {
      • "id": "012a94e4-76b4-5a5d-95ce-164577c9b5e5",
      • "name": "First-level taxonomy term",
      • "codename": "first_term",
      • "terms": [
        • {
          }
        ]
      }
    ]
}

Delete a taxonomy group

delete/projects/{environment_id}/taxonomies/{taxonomy_group_identifier}

Delete a taxonomy group specified by its internal ID, codename, or external ID.

If you delete a taxonomy group that is referenced in existing content items (i.e., for tagging content), the content items keep references to the deleted taxonomy term. To find the invalid references, validate your content. Then you can remove the found invalid references.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
taxonomy_group_identifier
required
string

The identifier of a specific taxonomy group. You can specify a taxonomy group by its internal ID (e.g., 0be13600-e57c-577d-8108-c8d860330985), external ID (e.g., external-id/Tax-Group-123), or codename {e.g., codename/personas).

Responses
204

The specified taxonomy group was deleted.

404

The specified taxonomy group was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteTaxonomy()
  .byTaxonomyId("dbff8416-c4c7-45d2-b497-a4a71a5cbe30")
  // .byTaxonomyCodename("personas_222")
  // .byTaxonomyExternalId("Tax-Group-124")
  .toPromise();
Response samples
application/json
{
  • "request_id": "9e6a2ec1-fb8e-49af-b1bc-011960ce4e2a",
  • "error_code": 107,
  • "message": "The requested taxonomy was not found."
}

Users

Users are specific people who have been invited to your Kontent.ai project and its environments.

The endpoints for managing users in project environments require Enterprise plan and the Invite and manage project members permission.

User object

user_id
required
string

The user's internal ID.

required
Array of objects

Specifies the permissions the user has in the environment based on the user's role and access to specific collections and languages.

{
  • "user_id": "d94bc87a-c066-48a1-a910-4f991ccc1fb5",
  • "collection_groups": [
    • {
      • "collections": [
        • {
          },
        • {
          }
        ],
      • "roles": [
        • {
          }
        ]
      }
    ]
}

User management

Management API and Subscription API together provide combined capabilities to manage users' access and assignments to your projects under a specified subscription.

Under a specified subscription, you can manage your users via Subscription API which enables you to:

You can also use Management API to invite users and change users' roles in your projects.

Invite a user

post/projects/{environment_id}/users

Invite a new user to your project and assign them a specific role. The user becomes active in the environment you invite them to, and deactivated in other environments.

If you invite the user as a Project manager, the user gains access to all environments in a given project.

This endpoint requires Enterprise plan and the Invite and manage project members permission.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json

The user to be invited.

email
required
string <email>

The user's email address.

required
Array of objects non-empty

Specifies the permissions the user has in the environment based on the user's role and access to specific collections and languages.

You can assign the user specific roles in different collections. At least one collection group must be specified.

Responses
201

An invitation was sent to the user.

400

The specified request body is invalid, or the user has already been invited.

Request samples
application/json
{
  • "email": "user@example.com",
  • "collection_groups": [
    • {
      • "collections": [
        • {
          },
        • {
          }
        ],
      • "roles": [
        • {
          }
        ]
      }
    ]
}
Response samples
application/json
{
  • "user_id": "d94bc87a-c066-48a1-a910-4f991ccc1fb5",
  • "collection_groups": [
    • {
      • "collections": [
        • {
          },
        • {
          }
        ],
      • "roles": [
        • {
          }
        ]
      }
    ]
}

Change a user's role

put/projects/{environment_id}/users/{user_identifier}/roles

Change the user's role and their access to content based on the user's assignment to roles, collections, and languages.

This endpoint requires Enterprise plan and the Invite and manage project members permission.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
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).

Example: mB9I0b-n-Zhe-x2my4NPjJovOiE0cqKgIyuVjqfKyW0
Request Body schema: application/json

User role, collection, and language assignments to be updated.

required
Array of objects non-empty unique

Specifies the permissions the user has in the environment based on the user's role and access to specific collections and languages.

You can assign the user specific roles in different collections. At least one collection group must be specified.

Array (non-empty)
required
Array of objects unique

Specifies the collections the user has access to.

Provide either references to collections, or an empty array to assign the user to all collections.

required
Array of objects non-empty

The roles the user is assigned to in a collection group. At least one role must be specified.

Responses
200

The user's roles were updated.

400

The specified request body or the role configuration is invalid.

403

The user tried to modify their own role.

404

The specified user was not found.

Request samples
application/json
{
  • "collection_groups": [
    • {
      • "collections": [
        • {
          },
        • {
          }
        ],
      • "roles": [
        • {
          }
        ]
      }
    ]
}
Response samples
application/json
{
  • "user_id": "d94bc87a-c066-48a1-a910-4f991ccc1fb5",
  • "collection_groups": [
    • {
      • "collections": [
        • {
          },
        • {
          }
        ],
      • "roles": [
        • {
          }
        ]
      }
    ]
}

Validation

After importing your content into Kontent.ai, you can validate your content to check for any issues.

The endpoints for content validation require either a Management API key with the Read content permission or a Personal API key.

How to validate your content

First, start a content validation to get a validation task. The validation task identifies the validation that you started and you'll use the task to check the progress of your validation.

The validation task lets you know whether the validation completed successfully and if there were any issues with content in the specified environment.

Validation task represents an asynchronous job.

id
required
string <uuid>

The validation task's internal ID.

status
required
string

The validation status lets you know how the validation is going.

Enum Value Description
queued

The content validation is still in progress.

finished

The content validation has been completed.

failed

The content validation failed with an error.

validation_result
required
string

The validation result lets you know if your content is fine or contains issues. If issues are found, you can list the validation results by providing the validation task's id.

Enum Value Description
none

There are no results because the validation is still in progress.

no_issues

The content is valid without any issues.

issues_found

Some of the content failed to validate.

{
  • "id": "12cf6682-3960-4cfc-851b-e765716e463a",
  • "status": "finished",
  • "validation_result": "no_issues"
}

If the validation task completes with its validation_result set to issues_found, your next step is to list the validation issues. This way you can check for errors and mistakes in your content and fix them.

Start content validation

post/projects/{environment_id}/validate-async

Start validating the specified environment's content to check for issues such as:

  • Missing objects that are referenced in content items.
  • Content element values that don't meet the limitations configured in content types.
  • Content types that reference missing taxonomy groups.

Depending on the amount of content in your environment, the validation might take several minutes.

After you start the content validation, you get a validation task. With the validation task, you can check validation progress and list validation results once the validation is finished.

This endpoint requires either a Management API key with the Read content permission or a Personal API key.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
202

A content validation task.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var response = await client.InitiateProjectAsyncValidationTaskAsync();
Response samples
application/json
{
  • "id": "12cf6682-3960-4cfc-851b-e765716e463a",
  • "status": "queued",
  • "validation_result": "none"
}

Check content validation progress

get/projects/{environment_id}/validate-async/tasks/{task_id}

Retrieves information about a content validation task by the task's internal ID.

This endpoint requires either a Management API key with the Read content permission or a Personal API key.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
task_id
required
string

The validation task's internal ID.

Example: 60917551-1a77-4184-bd8e-76ad3edd20da
Responses
200

The specified content validation task. The content validation task is available for 7 days from the time of creation.

404

The specified content validation task was not found.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var response = await client.GetAsyncValidationTaskAsync(Guid.Parse("88d94fed-4899-4944-9b4b-c919b11a9db0"));
Response samples
application/json
{
  • "id": "12cf6682-3960-4cfc-851b-e765716e463a",
  • "status": "finished",
  • "validation_result": "no_issues"
}

List content validation results

get/projects/{environment_id}/validate-async/tasks/{task_id}/issues

Retrieves a dynamically paginated list of content validation issues.

This endpoint requires either a Management API key with the Read content permission or a Personal API key.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
task_id
required
string

The validation task's internal ID.

Example: 60917551-1a77-4184-bd8e-76ad3edd20da
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.

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of content validation issues.

400

The specified continuation token is incorrect.

404

The specified content validation task was not found.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var response = await client.ListAsyncValidationTaskIssuesAsync(Guid.Parse("88d94fed-4899-4944-9b4b-c919b11a9db0"));
Response samples
application/json
{
  • "issues": [
    • {
      • "issue_type": "variant_issue",
      • "item": {
        • "id": "b2fea94c-73fd-42ec-a22f-f409878de187",
        • "name": "My article",
        • "codename": "my_article"
        },
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000",
        • "name": "English (United States)",
        • "codename": "default"
        },
      • "issues": [
        • {
          }
        ]
      }
    ],
  • "pagination": {}
}

Validate contentDeprecated

post/projects/{environment_id}/validate

Checks content items in the specified environment for issues such as:

  • Content elements that reference missing objects.
  • Content elements that don't meet the limitations configured in content types.
  • Content types that reference missing taxonomy groups.

Deprecation notice

This endpoint works reliably only for environments that contain under 25,000 content items. Use the new project validation approach to validate environments of any size.

This endpoint requires either a Management API key with the Read content permission or a Personal API key.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

A report summarizing the issues found in the specified environment.

Request samples 
// 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_ENVIRONMENT_ID>"
});

var response = await client.ValidateProjectAsync();
Response samples
application/json
{
  • "project": {
    • "id": "8d20758c-d74c-4f59-ae04-ee928c0816b7",
    • "name": "Sample project",
    • "environment": "Production",
    • "is_production": "true"
    },
  • "variant_issues": [
    • {
      • "item": {
        • "id": "b2fea94c-73fd-42ec-a22f-f409878de187",
        • "name": "My article",
        • "codename": "my_article"
        },
      • "language": {
        • "id": "00000000-0000-0000-0000-000000000000",
        • "name": "English (United States)",
        • "codename": "default"
        },
      • "issues": [
        • {
          }
        ]
      }
    ],
  • "type_issues": [
    • {
      • "type": {
        • "id": "929985ac-4aa5-436b-85a2-94c2d4fbbebd",
        • "name": "Article",
        • "codename": "article"
        },
      • "issues": [
        • {
          }
        ]
      }
    ]
}

Webhooks

Use webhooks to receive real-time notifications about changes in your environments. You can get notified about changes in your assets, content items, content types, languages, and taxonomy groups. Learn more about how to set up webhooks.

Webhook object

The webhook object specifies the configuration for a webhook in your environment. This includes the webhook URL, a secret key for validating notification authenticity, and details about the events that trigger the webhook.

id
string <uuid>

The webhook's internal ID.

name
required
string [ 1 .. 200 ] characters

The webhook's display name.

url
required
string <url> [ 1 .. 250 ] characters

The webhook's URL. Kontent.ai will send notifications to this URL.

secret
required
string

The webhook's secret key. Use the secret key to validate notification authenticity.

When creating webhooks via API, you need to provide your own secret value. We recommend using a CSPRNG for this. In the UI, the secret is automatically generated for you.

Array of objects [ 0 .. 10 ] items

The webhook's custom HTTP headers. This is useful if you need to send extra information, such as authentication details, along with the webhook notification body.

If you specify multiple headers with the same key for the webhook, the header values will be added to a comma-separated list and sent as a single HTTP header, such as "custom_key": "value1, value2, value3".

enabled
boolean

Determines if the webhook is enabled. By default, the enabled property is set to true.

  • Enabled webhooks react to the defined triggers, create notifications, and try to send the notifications to the specified webhook URL in the order of creation.
  • Disabled webhooks ignore the defined triggers and do not create any notifications.
last_modified
string <date-time>

ISO-8601 formatted date & time of the last change to the webhook.

health_status
string

The webhook's health status tells you whether the webhook is operational. Use this information to debug your webhooks.

Enum Value Description
unknown

Appears for newly created webhooks before any notification is sent.

working

Appears for webhooks that have successfully delivered notifications.

failing

Appears for webhooks that have not been successful in delivering notifications. This means Kontent.ai received a response other than a 20X.

The webhook notifications are still being sent based on the retry policy. If you’ve issued a fix and want to reset the retry policy, you can reset the webhook.

… 1 more
required
object

Specifies which events will trigger the webhook. The events can be set for the published or preview data in Delivery API.

{
  • "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
  • "name": "Example webhook",
  • "url": "https://example.com/webhook",
  • "secret": "fNp+QH1sE+fSXoNFlQ4kwiTJz0er2L34gFItAAVHws8=",
  • "headers": [
    • {
      • "key": "api-key",
      • "value": "Secret API key value"
      },
    • {
      • "key": "Custom-key",
      • "value": "Custom header value with alphanum3r1c characters."
      }
    ],
  • "enabled": "true",
  • "last_modified": "2023-09-18T09:29:08.4356117Z",
  • "health_status": "working",
  • "delivery_triggers": {
    • "slot": "preview",
    • "events": "specific",
    • "content_type": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "content_types": [
          ]
        }
      },
    • "content_item": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "collections": [
          ],
        • "content_types": [
          ],
        • "languages": [
          ]
        }
      },
    • "taxonomy": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "taxonomies": [
          ]
        }
      },
    • "asset": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ]
      },
    • "language": {
      • "enabled": "true",
      • "actions": [
        • {
          },
        • {
          }
        ],
      • "filters": {
        • "languages": [
          ]
        }
      }
    }
}

Add a webhook

post/projects/{environment_id}/webhooks-vnext

Add a webhook to a given environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json

The webhook to be added.

name
required
string [ 1 .. 200 ] characters

The webhook's display name.

url
required
string <url> [ 1 .. 250 ] characters

The webhook's URL. Kontent.ai will send notifications to this URL.

secret
required
string

The webhook's secret key. Use the secret key to validate notification authenticity.

When creating webhooks via API, you need to provide your own secret value. We recommend using a CSPRNG for this. In the UI, the secret is automatically generated for you.

Array of objects [ 0 .. 10 ] items

The webhook's custom HTTP headers. This is useful if you need to send extra information, such as authentication details, along with the webhook notification body.

If you specify multiple headers with the same key for the webhook, the header values will be added to a comma-separated list and sent as a single HTTP header, such as "custom_key": "value1, value2, value3".

enabled
boolean

Determines if the webhook is enabled. By default, the enabled property is set to true.

  • Enabled webhooks react to the defined triggers, create notifications, and try to send the notifications to the specified webhook URL in the order of creation.
  • Disabled webhooks ignore the defined triggers and do not create any notifications.
required
object

Specifies which events will trigger the webhook. The events can be set for the published or preview data in Delivery API.

Responses
201

The added webhook object.

400

The specified request body is invalid.

Request samples
application/json
{
  • "name": "Example webhook",
  • "url": "https://example.com/webhook",
  • "secret": "fNp+QH1sE+fSXoNFlQ4kwiTJz0er2L34gFItAAVHws8=",
  • "headers": [
    • {
      • "key": "api-key",
      • "value": "Secret API key value"
      },
    • {
      • "key": "Custom-key",
      • "value": "Custom header value with alphanum3r1c characters."
      }
    ],
  • "enabled": "true",
  • "delivery_triggers": {
    • "slot": "preview",
    • "events": "specific",
    • "content_type": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "content_types": [
          ]
        }
      },
    • "content_item": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "collections": [
          ],
        • "content_types": [
          ],
        • "languages": [
          ]
        }
      },
    • "taxonomy": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "taxonomies": [
          ]
        }
      },
    • "asset": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ]
      },
    • "language": {
      • "enabled": "true",
      • "actions": [
        • {
          },
        • {
          }
        ],
      • "filters": {
        • "languages": [
          ]
        }
      }
    }
}
Response samples
application/json
{
  • "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
  • "name": "Example webhook",
  • "url": "https://example.com/webhook",
  • "secret": "fNp+QH1sE+fSXoNFlQ4kwiTJz0er2L34gFItAAVHws8=",
  • "headers": [
    • {
      • "key": "api-key",
      • "value": "Secret API key value"
      },
    • {
      • "key": "Custom-key",
      • "value": "Custom header value with alphanum3r1c characters."
      }
    ],
  • "enabled": "true",
  • "last_modified": "2023-09-18T09:29:08.4356117Z",
  • "health_status": "working",
  • "delivery_triggers": {
    • "slot": "preview",
    • "events": "specific",
    • "content_type": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "content_types": [
          ]
        }
      },
    • "content_item": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "collections": [
          ],
        • "content_types": [
          ],
        • "languages": [
          ]
        }
      },
    • "taxonomy": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "taxonomies": [
          ]
        }
      },
    • "asset": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ]
      },
    • "language": {
      • "enabled": "true",
      • "actions": [
        • {
          },
        • {
          }
        ],
      • "filters": {
        • "languages": [
          ]
        }
      }
    }
}

Retrieve webhooks

get/projects/{environment_id}/webhooks-vnext

Retrieves webhooks from an environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

A list of webhooks.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.listWebhooks()
  .toPromise();
Response samples
application/json
[
  • {
    • "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
    • "name": "Example webhook",
    • "url": "https://example.com/webhook",
    • "secret": "fNp+QH1sE+fSXoNFlQ4kwiTJz0er2L34gFItAAVHws8=",
    • "headers": [
      • {
        • "key": "api-key",
        • "value": "Secret API key value"
        },
      • {
        • "key": "Custom-key",
        • "value": "Custom header value with alphanum3r1c characters."
        }
      ],
    • "enabled": "true",
    • "last_modified": "2023-09-18T09:29:08.4356117Z",
    • "health_status": "working",
    • "delivery_triggers": {
      • "slot": "preview",
      • "events": "specific",
      • "content_type": {
        • "enabled": "true",
        • "actions": [
          ],
        • "filters": {
          }
        },
      • "content_item": {
        • "enabled": "true",
        • "actions": [
          ],
        • "filters": {
          }
        },
      • "taxonomy": {
        • "enabled": "true",
        • "actions": [
          ],
        • "filters": {
          }
        },
      • "asset": {
        • "enabled": "true",
        • "actions": [
          ]
        },
      • "language": {
        • "enabled": "true",
        • "actions": [
          ],
        • "filters": {
          }
        }
      }
    }
]

Retrieve a webhook

get/projects/{environment_id}/webhooks-vnext/{webhook_identifier}

Retrieves a webhook specified by its internal ID.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
webhook_identifier
required
string

Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Example: 5df74e27-1213-484e-b9ae-bcbe90bd5990
Responses
200

A single webhook object.

404

The specified webhook was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.getWebhook()
  .byId("5df74e27-1213-484e-b9ae-bcbe90bd5990")
  .toPromise();
Response samples
application/json
{
  • "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
  • "name": "Example webhook",
  • "url": "https://example.com/webhook",
  • "secret": "fNp+QH1sE+fSXoNFlQ4kwiTJz0er2L34gFItAAVHws8=",
  • "headers": [
    • {
      • "key": "api-key",
      • "value": "Secret API key value"
      },
    • {
      • "key": "Custom-key",
      • "value": "Custom header value with alphanum3r1c characters."
      }
    ],
  • "enabled": "true",
  • "last_modified": "2023-09-18T09:29:08.4356117Z",
  • "health_status": "working",
  • "delivery_triggers": {
    • "slot": "preview",
    • "events": "specific",
    • "content_type": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "content_types": [
          ]
        }
      },
    • "content_item": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "collections": [
          ],
        • "content_types": [
          ],
        • "languages": [
          ]
        }
      },
    • "taxonomy": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ],
      • "filters": {
        • "taxonomies": [
          ]
        }
      },
    • "asset": {
      • "enabled": "true",
      • "actions": [
        • {
          }
        ]
      },
    • "language": {
      • "enabled": "true",
      • "actions": [
        • {
          },
        • {
          }
        ],
      • "filters": {
        • "languages": [
          ]
        }
      }
    }
}

Delete a webhook

delete/projects/{environment_id}/webhooks-vnext/{webhook_identifier}

Delete a webhook specified by its internal ID.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
webhook_identifier
required
string

Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Example: 5df74e27-1213-484e-b9ae-bcbe90bd5990
Responses
204

The specified webhook was deleted.

404

The specified webhook was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteWebhook()
  .byId("d53360f7-79e1-42f4-a524-1b53a417d03e")
  .toPromise();
Response samples
application/json
{
  • "request_id": "|4917a91f0f3c1640a41e5afda87f57b5.9fa110d9_",
  • "error_code": 111,
  • "message": "The requested webhook was not found."
}

Enable a webhook

put/projects/{environment_id}/webhooks-vnext/{webhook_identifier}/enable

Enables a webhook specified by its internal ID.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
webhook_identifier
required
string

Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Example: 5df74e27-1213-484e-b9ae-bcbe90bd5990
Responses
204

The specified webhook was enabled.

404

The specified webhook was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.enableWebhook()
  .byId("5df74e27-1213-484e-b9ae-bcbe90bd5990")
  .toPromise();
Response samples
application/json
{
  • "request_id": "|f5e9980562323e4b9b23588a141d323a.2774b2ca_",
  • "error_code": 111,
  • "message": "The requested webhook was not found."
}

Disable a webhook

put/projects/{environment_id}/webhooks-vnext/{webhook_identifier}/disable

Disables a webhook specified by its internal ID.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
webhook_identifier
required
string

Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Example: 5df74e27-1213-484e-b9ae-bcbe90bd5990
Responses
204

The specified webhook was disabled.

404

The specified webhook was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.disableWebhook()
  .byId("5df74e27-1213-484e-b9ae-bcbe90bd5990")
  .toPromise();
Response samples
application/json
{
  • "request_id": "|f5e9980562323e4b9b23588a141d323a.2774b2ca_",
  • "error_code": 111,
  • "message": "The requested webhook was not found."
}

Webhooks legacy

Webhooks are useful for receiving immediate notifications when something changes, such as newly published content. Learn more about how to use and debug webhooks.

The legacy webhooks are available only for subscriptions created before December 14, 2023. We recommend using the default webhooks.

Legacy webhook object

The legacy webhook object specifies the configuration for a webhook in your environment. This includes the webhook URL, a secret key for verifying notification authenticity, and details about the events that trigger the webhook.

last_modified
string <date-time>

ISO-8601 formatted date/time of the last change to the webhook.

health_status
string

The webhook's health status tells you whether the webhook is operational. You can use this information for webhook debugging.

Enum Value Description
unknown

Appears for newly created webhooks before any notification has been sent.

working

Appears for webhooks that have properly delivered notifications.

failing

Appears for webhooks that have not been delivered properly (received a response other than a 20X HTTP status code). These webhook notifications are still being sent based on the retry policy. You can also reset the webhook if you’ve issued a fix and want to reset the retry policy.

… 1 more
id
string <uuid>

The webhook's internal ID.

name
required
string [ 1 .. 200 ] characters

The webhook's display name.

url
required
string <url> [ 1 .. 250 ] characters

The URL to which the webhook notification will be sent.

secret
required
string non-empty

The webhook's secret key. Use the secret to verify your webhoo came from Kontent.ai.

When creating webhooks via API, you need to provide your own secret value. We recommend using a CSPRNG for this. In the UI, the secret is generated for you.

enabled
boolean

Determines if the webhook is enabled. By default, the enabled property is set to true.

  • Enabled webhook reacts to the defined triggers, creates notifications, and tries to send the notifications in order of creation to the specified webhook URL.
  • Disabled webhook ignores the defined triggers and does not create any notifications.
required
object

The specific events that trigger the webhook. At least one valid trigger is required.

Once the webhook is triggered, it adds a notification to its queue and tries to send it to the webhook URL.

{
  • "last_modified": "2019-09-18T09:29:08.4356117Z",
  • "health_status": "working",
  • "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
  • "name": "Example webhook",
  • "url": "https://example.com/webhook",
  • "secret": "fd1OvtRK549lUCwNKkjQylDJBPKm0O0/pbJmrPtTW+U=",
  • "enabled": "true",
  • "triggers": {
    • "delivery_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        },
      • {
        • "type": "taxonomy",
        • "operations": [
          ]
        }
      ],
    • "preview_delivery_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        },
      • {
        • "type": "taxonomy",
        • "operations": [
          ]
        }
      ],
    • "workflow_step_changes": [
      • {
        • "type": "content_item_variant",
        • "transitions_to": [
          ]
        }
      ],
    • "management_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        }
      ]
    }
}

Add a legacy webhook

post/projects/{environment_id}/webhooks

Add a legacy webhook to an environment.

The legacy webhooks are available only for subscriptions created before December 14, 2023. We recommend using the default webhooks.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json

The webhook to be added.

health_status
string

The webhook's health status tells you whether the webhook is operational. You can use this information for webhook debugging.

Enum Value Description
unknown

Appears for newly created webhooks before any notification has been sent.

working

Appears for webhooks that have properly delivered notifications.

failing

Appears for webhooks that have not been delivered properly (received a response other than a 20X HTTP status code). These webhook notifications are still being sent based on the retry policy. You can also reset the webhook if you’ve issued a fix and want to reset the retry policy.

… 1 more
name
required
string [ 1 .. 200 ] characters

The webhook's display name.

url
required
string <url> [ 1 .. 250 ] characters

The URL to which the webhook notification will be sent.

secret
required
string non-empty

The webhook's secret key. Use the secret to verify your webhoo came from Kontent.ai.

When creating webhooks via API, you need to provide your own secret value. We recommend using a CSPRNG for this. In the UI, the secret is generated for you.

enabled
boolean

Determines if the webhook is enabled. By default, the enabled property is set to true.

  • Enabled webhook reacts to the defined triggers, creates notifications, and tries to send the notifications in order of creation to the specified webhook URL.
  • Disabled webhook ignores the defined triggers and does not create any notifications.
required
object

The specific events that trigger the webhook. At least one valid trigger is required.

Once the webhook is triggered, it adds a notification to its queue and tries to send it to the webhook URL.

Responses
201

The added legacy webhook object.

400

The specified request body is invalid.

Request samples
application/json
{
  • "health_status": "working",
  • "name": "Example webhook",
  • "url": "https://example.com/webhook",
  • "secret": "fd1OvtRK549lUCwNKkjQylDJBPKm0O0/pbJmrPtTW+U=",
  • "enabled": "true",
  • "triggers": {
    • "delivery_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        },
      • {
        • "type": "taxonomy",
        • "operations": [
          ]
        }
      ],
    • "preview_delivery_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        },
      • {
        • "type": "taxonomy",
        • "operations": [
          ]
        }
      ],
    • "workflow_step_changes": [
      • {
        • "type": "content_item_variant",
        • "transitions_to": [
          ]
        }
      ],
    • "management_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        }
      ]
    }
}
Response samples
application/json
{
  • "last_modified": "2019-09-18T09:29:08.4356117Z",
  • "health_status": "working",
  • "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
  • "name": "Example webhook",
  • "url": "https://example.com/webhook",
  • "secret": "fd1OvtRK549lUCwNKkjQylDJBPKm0O0/pbJmrPtTW+U=",
  • "enabled": "true",
  • "triggers": {
    • "delivery_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        },
      • {
        • "type": "taxonomy",
        • "operations": [
          ]
        }
      ],
    • "preview_delivery_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        },
      • {
        • "type": "taxonomy",
        • "operations": [
          ]
        }
      ],
    • "workflow_step_changes": [
      • {
        • "type": "content_item_variant",
        • "transitions_to": [
          ]
        }
      ],
    • "management_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        }
      ]
    }
}

Retrieve legacy webhooks

get/projects/{environment_id}/webhooks

Retrieves legacy webhooks from an environment.

The legacy webhooks are available only for subscriptions created before December 14, 2023. We recommend using the default webhooks.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

A list of legacy webhooks.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.listLegacyWebhooks()
  .toPromise();
Response samples
application/json
[
  • {
    • "last_modified": "2019-09-18T09:29:08.4356117Z",
    • "health_status": "working",
    • "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
    • "name": "Example webhook",
    • "url": "https://example.com/webhook",
    • "secret": "fd1OvtRK549lUCwNKkjQylDJBPKm0O0/pbJmrPtTW+U=",
    • "enabled": "true",
    • "triggers": {
      • "delivery_api_content_changes": [
        • {
          },
        • {
          }
        ],
      • "preview_delivery_api_content_changes": [
        • {
          },
        • {
          }
        ],
      • "workflow_step_changes": [
        • {
          }
        ],
      • "management_api_content_changes": [
        • {
          }
        ]
      }
    }
]

Retrieve a legacy webhook

get/projects/{environment_id}/webhooks/{webhook_identifier}

Retrieves a legacy webhook specified by its internal ID.

The legacy webhooks are available only for subscriptions created before December 14, 2023. We recommend using the default webhooks.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
webhook_identifier
required
string

Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Example: 5df74e27-1213-484e-b9ae-bcbe90bd5990
Responses
200

A single legacy webhook object.

404

The specified legacy webhook was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.getLegacyWebhook()
  .byId("5df74e27-1213-484e-b9ae-bcbe90bd5990")
  .toPromise();
Response samples
application/json
{
  • "last_modified": "2019-09-18T09:29:08.4356117Z",
  • "health_status": "working",
  • "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
  • "name": "Example webhook",
  • "url": "https://example.com/webhook",
  • "secret": "fd1OvtRK549lUCwNKkjQylDJBPKm0O0/pbJmrPtTW+U=",
  • "enabled": "true",
  • "triggers": {
    • "delivery_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        },
      • {
        • "type": "taxonomy",
        • "operations": [
          ]
        }
      ],
    • "preview_delivery_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        },
      • {
        • "type": "taxonomy",
        • "operations": [
          ]
        }
      ],
    • "workflow_step_changes": [
      • {
        • "type": "content_item_variant",
        • "transitions_to": [
          ]
        }
      ],
    • "management_api_content_changes": [
      • {
        • "type": "content_item_variant",
        • "operations": [
          ]
        }
      ]
    }
}

Delete a legacy webhook

delete/projects/{environment_id}/webhooks/{webhook_identifier}

Delete a legacy webhook specified by its internal ID.

The legacy webhooks are available only for subscriptions created before December 14, 2023. We recommend using the default webhooks.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
webhook_identifier
required
string

Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Example: 5df74e27-1213-484e-b9ae-bcbe90bd5990
Responses
204

The specified legacy webhook was deleted.

404

The specified legacy webhook was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteLegacyWebhook()
  .byId("d53360f7-79e1-42f4-a524-1b53a417d03e")
  .toPromise();
Response samples
application/json
{
  • "request_id": "|4917a91f0f3c1640a41e5afda87f57b5.9fa110d9_",
  • "error_code": 111,
  • "message": "The requested webhook was not found."
}

Enable a legacy webhook

put/projects/{environment_id}/webhooks/{webhook_identifier}/enable

Enables a legacy webhook specified by its internal ID.

The legacy webhooks are available only for subscriptions created before December 14, 2023. We recommend using the default webhooks.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
webhook_identifier
required
string

Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Example: 5df74e27-1213-484e-b9ae-bcbe90bd5990
Responses
204

The specified legacy webhook was enabled.

404

The specified legacy webhook was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.enableLegacyWebhook()
  .byId("5df74e27-1213-484e-b9ae-bcbe90bd5990")
  .toPromise();
Response samples
application/json
{
  • "request_id": "|f5e9980562323e4b9b23588a141d323a.2774b2ca_",
  • "error_code": 111,
  • "message": "The requested webhook was not found."
}

Disable a legacy webhook

put/projects/{environment_id}/webhooks/{webhook_identifier}/disable

Disables a legacy webhook specified by its internal ID.

The legacy webhooks are available only for subscriptions created before December 14, 2023. We recommend using the default webhooks.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
webhook_identifier
required
string

Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Example: 5df74e27-1213-484e-b9ae-bcbe90bd5990
Responses
204

The specified legacy webhook was disabled.

404

The specified legacy webhook was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.disableLegacyWebhook()
  .byId("5df74e27-1213-484e-b9ae-bcbe90bd5990")
  .toPromise();
Response samples
application/json
{
  • "request_id": "|f5e9980562323e4b9b23588a141d323a.2774b2ca_",
  • "error_code": 111,
  • "message": "The requested webhook was not found."
}

Workflows

Every project environment comes with a single workflow marked as Default. In subscriptions with Multiple workflows, your environments might contain several workflows with different workflow steps.

The workflows themselves consist of a number of steps, with two predefined steps, Published and Archived. Workflow steps indicate a specific stage in the content production process. For example, Draft -> Review -> Legal approval -> Published. Every variant of a content item (such as English, Spanish, French) can be moved to a specific workflow step.

The combination of workflow and its workflow step might affect who can edit the variant and who can move the variant to another workflow step. Check how to set up a workflow for your content.

Workflow object

id
string <uuid>

The workflow's internal ID. The ID of the default workflow is always 00000000-0000-0000-0000-000000000000.

name
required
string [ 1 .. 200 ] characters

The workflow's display name.

codename
string [ 1 .. 60 ] characters

The workflow's codename.

required
Array of objects >= 0 items

Specifies the content types and collections that this workflow is limited to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other workflow.

Changing the workflow's scope doesn't affect existing content items unless you change their workflow manually.

required
Array of objects

The workflow steps in this workflow.

required
object

The workflow's predefined Published workflow step.

object

The workflow's predefined Scheduled workflow step.

required
object

The workflow's predefined Archived workflow step.

{
  • "id": "8e38928b-50b6-4e9e-ab53-af35d6fcfcb8",
  • "name": "My workflow",
  • "codename": "my_workflow",
  • "scopes": [
    • {
      • "content_types": [
        • {
          },
        • {
          }
        ],
      • "collections": [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "steps": [
    • {
      • "id": "b288d00b-f5cd-4afe-97fc-42b9264404f3",
      • "name": "Draft",
      • "codename": "draft",
      • "color": "red",
      • "transitions_to": [
        • {
          },
        • {
          }
        ],
      • "role_ids": [
        • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
        ]
      }
    ],
  • "published_step": {
    • "id": "c199950d-99f0-4983-b711-6c4c91624b22",
    • "name": "Published",
    • "codename": "published",
    • "unpublish_role_ids": [
      • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ],
    • "create_new_version_role_ids": [
      • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ]
    },
  • "scheduled_step": {
    • "id": "9d2b0228-4d0d-4c23-8b49-01a698857709",
    • "name": "Scheduled",
    • "codename": "scheduled"
    },
  • "archived_step": {
    • "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
    • "name": "Archived",
    • "codename": "archived",
    • "role_ids": [
      • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ]
    }
}

Add a workflow

post/projects/{environment_id}/workflows

Create a new workflow.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Request Body schema: application/json
required

Specify the new workflow.

name
required
string [ 1 .. 200 ] characters

The workflow's display name.

codename
string [ 1 .. 60 ] characters

The workflow's codename.

required
Array of objects >= 0 items

Specifies the content types and collections that this workflow is limited to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other workflow.

Changing the workflow's scope doesn't affect existing content items unless you change their workflow manually.

required
Array of objects

The workflow steps in this workflow.

required
object

The workflow's predefined Published workflow step.

required
object

The workflow's predefined Archived workflow step.

Responses
201

The created workflow.

400

The specified request body is invalid.

Request samples
application/json
{
  • "name": "My workflow",
  • "scopes": [
    • {
      • "content_types": [
        • {
          }
        ],
      • "collections": [
        • {
          }
        ]
      }
    ],
  • "steps": [
    • {
      • "name": "First step",
      • "codename": "first_step",
      • "color": "sky-blue",
      • "transitions_to": [
        • {
          }
        ],
      • "role_ids": [ ]
      },
    • {
      • "name": "Second step",
      • "codename": "second_step",
      • "color": "rose",
      • "transitions_to": [
        • {
          }
        ],
      • "role_ids": [
        • "e796887c-38a1-4ab2-a999-c40861bb7a4b"
        ]
      }
    ],
  • "published_step": {
    • "unpublish_role_ids": [
      • "e796887c-38a1-4ab2-a999-c40861bb7a4b"
      ],
    • "create_new_version_role_ids": [ ]
    },
  • "archived_step": {
    • "role_ids": [ ]
    }
}
Response samples
application/json
{
  • "id": "705c3bd8-29c6-466c-b42b-6c6c3887786e",
  • "name": "My workflow",
  • "codename": "my_workflow",
  • "scopes": [
    • {
      • "content_types": [
        • {
          }
        ],
      • "collections": [
        • {
          }
        ]
      }
    ],
  • "steps": [
    • {
      • "id": "2044477d-36aa-4ad5-91de-eaa2927ab173",
      • "name": "First step",
      • "codename": "first_step",
      • "color": "sky-blue",
      • "transitions_to": [
        • {
          }
        ],
      • "role_ids": [ ]
      },
    • {
      • "id": "c236dedd-a216-47fa-b0c0-0ea33877f357",
      • "name": "Second step",
      • "codename": "second_step",
      • "color": "rose",
      • "transitions_to": [
        • {
          }
        ],
      • "role_ids": [
        • "e796887c-38a1-4ab2-a999-c40861bb7a4b"
        ]
      }
    ],
  • "published_step": {
    • "id": "c199950d-99f0-4983-b711-6c4c91624b22",
    • "name": "Published",
    • "codename": "published",
    • "unpublish_role_ids": [
      • "e796887c-38a1-4ab2-a999-c40861bb7a4b"
      ],
    • "create_new_version_role_ids": [ ]
    },
  • "archived_step": {
    • "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
    • "name": "Archived",
    • "codename": "archived",
    • "role_ids": [ ]
    }
}

Retrieve workflows

get/projects/{environment_id}/workflows

Retrieve a list of workflows with information about the workflow steps they define.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

Workflows in the specified environment.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.listWorkflows()
  .toPromise();
Response samples
application/json
[
  • {
    • "id": "8e38928b-50b6-4e9e-ab53-af35d6fcfcb8",
    • "name": "My workflow",
    • "codename": "my_workflow",
    • "scopes": [
      • {
        • "content_types": [
          ],
        • "collections": [
          ]
        }
      ],
    • "steps": [
      • {
        • "id": "b288d00b-f5cd-4afe-97fc-42b9264404f3",
        • "name": "Draft",
        • "codename": "draft",
        • "color": "red",
        • "transitions_to": [
          ],
        • "role_ids": [
          ]
        }
      ],
    • "published_step": {
      • "id": "c199950d-99f0-4983-b711-6c4c91624b22",
      • "name": "Published",
      • "codename": "published",
      • "unpublish_role_ids": [
        • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
        ],
      • "create_new_version_role_ids": [
        • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
        ]
      },
    • "scheduled_step": {
      • "id": "9d2b0228-4d0d-4c23-8b49-01a698857709",
      • "name": "Scheduled",
      • "codename": "scheduled"
      },
    • "archived_step": {
      • "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
      • "name": "Archived",
      • "codename": "archived",
      • "role_ids": [
        • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
        ]
      }
    }
]

Retrieve workflow stepsDeprecated

get/projects/{environment_id}/workflow

Get the workflow steps from the default workflow in your environment.

Use a new endpoint

Starting April 2022, this endpoint has been deprecated in favor of the new endpoint that supports multiple workflows.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
Responses
200

A list of workflow steps in the specified environment.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.listWorkflows()
  .toPromise();
const steps = response.data.find(workflow => workflow.codeName === 'default').steps;
Response samples
application/json
[
  • {
    • "id": "eee6db3b-545a-4785-8e86-e3772c8756f9",
    • "name": "Draft",
    • "codename": "draft",
    • "transitions_to": [
      • "c199950d-99f0-4983-b711-6c4c91624b22",
      • "7a535a69-ad34-47f8-806a-def1fdf4d391"
      ]
    },
  • {
    • "id": "9d2b0228-4d0d-4c23-8b49-01a698857709",
    • "name": "Scheduled",
    • "codename": "scheduled",
    • "transitions_to": [ ]
    },
  • {
    • "id": "c199950d-99f0-4983-b711-6c4c91624b22",
    • "name": "Published",
    • "codename": "published",
    • "transitions_to": [ ]
    },
  • {
    • "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
    • "name": "Archived",
    • "codename": "archived",
    • "transitions_to": [ ]
    }
]

Update a workflow

put/projects/{environment_id}/workflows/{workflow_identifier}

Update an existing workflow, manage its scope, workflow steps and their transitions, and role permissions. Always make sure that all steps eventually transition to the Published step.

When removing a workflow step, make sure the step is not in use. You can't remove a used workflow step.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
workflow_identifier
required
string

Identifies the workflow by its internal ID (e.g., 8bfdb62d-7aa1-473b-9d80-311ef93db108) or codename (e.g., codename/my-workflow).

Example: 8bfdb62d-7aa1-473b-9d80-311ef93db108
Request Body schema: application/json
required

Specify what you want to update in the workflow.

name
required
string [ 1 .. 200 ] characters

The workflow's display name.

codename
string [ 1 .. 60 ] characters

The workflow's codename.

required
Array of objects >= 0 items

Specifies the content types and collections that this workflow is limited to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other workflow.

Changing the workflow's scope doesn't affect existing content items unless you change their workflow manually.

required
Array of objects

The workflow steps in this workflow.

Prefer codenames over IDs when referring to workflow steps

You can reference existing workflow steps by their codename or ID. We recommend using codenames because it makes your code cleaner and easier to manage. Use ID only when you need to change the codename of a workflow step.

If you want to reuse codenames of existing workflow steps in new workflow steps, you need to make two requests. First remove the workflow step with the desired codename. This make the codename available. Then add a new workflow step.

required
object

The workflow's predefined Published workflow step.

required
object

The workflow's predefined Archived workflow step.

Responses
200

The updated workflow.

400

The specified request body is invalid.

404

The specified workflow was not found.

Request samples
application/json
{
  • "name": "My workflow",
  • "scopes": [
    • {
      • "content_types": [
        • {
          }
        ],
      • "collections": [
        • {
          }
        ]
      }
    ],
  • "codename": "my-workflow",
  • "steps": [
    • {
      • "name": "First step",
      • "codename": "first_step",
      • "color": "sky-blue",
      • "transitions_to": [
        • {
          }
        ],
      • "role_ids": [ ]
      },
    • {
      • "name": "Second step",
      • "codename": "second_step",
      • "color": "rose",
      • "transitions_to": [
        • {
          }
        ],
      • "role_ids": [
        • "e796887c-38a1-4ab2-a999-c40861bb7a4b"
        ]
      }
    ],
  • "published_step": {
    • "unpublish_role_ids": [
      • "e796887c-38a1-4ab2-a999-c40861bb7a4b"
      ],
    • "create_new_version_role_ids": [ ]
    },
  • "archived_step": {
    • "role_ids": [ ]
    }
}
Response samples
application/json
{
  • "id": "8e38928b-50b6-4e9e-ab53-af35d6fcfcb8",
  • "name": "My workflow",
  • "codename": "my_workflow",
  • "scopes": [
    • {
      • "content_types": [
        • {
          },
        • {
          }
        ],
      • "collections": [
        • {
          },
        • {
          }
        ]
      }
    ],
  • "steps": [
    • {
      • "id": "b288d00b-f5cd-4afe-97fc-42b9264404f3",
      • "name": "Draft",
      • "codename": "draft",
      • "color": "red",
      • "transitions_to": [
        • {
          },
        • {
          }
        ],
      • "role_ids": [
        • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
        ]
      }
    ],
  • "published_step": {
    • "id": "c199950d-99f0-4983-b711-6c4c91624b22",
    • "name": "Published",
    • "codename": "published",
    • "unpublish_role_ids": [
      • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ],
    • "create_new_version_role_ids": [
      • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ]
    },
  • "scheduled_step": {
    • "id": "9d2b0228-4d0d-4c23-8b49-01a698857709",
    • "name": "Scheduled",
    • "codename": "scheduled"
    },
  • "archived_step": {
    • "id": "7a535a69-ad34-47f8-806a-def1fdf4d391",
    • "name": "Archived",
    • "codename": "archived",
    • "role_ids": [
      • "e25d74b8-f81a-4faf-94b9-b0bf2b3802c6"
      ]
    }
}

Delete a workflow

delete/projects/{environment_id}/workflows/{workflow_identifier}

Deletes an unused workflow.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
workflow_identifier
required
string

Identifies the workflow by its internal ID (e.g., 8bfdb62d-7aa1-473b-9d80-311ef93db108) or codename (e.g., codename/my-workflow).

Example: 8bfdb62d-7aa1-473b-9d80-311ef93db108
Responses
204

The specified workflow was deleted.

400

The workflow is in use, or it's the default workflow.

404

The specified workflow was not found.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
// Using ES6 syntax
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>',
  apiKey: '<YOUR_API_KEY>'
});

const response = await client.deleteWorkflow()
  .byWorkflowId("f9f28df0-9dec-4ee3-b087-c501e4b75347")
  //.byWorkflowCodename("my-workflow")
  .toPromise();
Response samples
application/json
{
  • "request_id": "703be4d0773e5647",
  • "error_code": 235,
  • "message": "The default workflow '00000000-0000-0000-0000-000000000000' cannot be deleted."
}