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 v2 to manage your content & assets, content model, environment settings, and users.
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.
Try the Kontent.ai APIs in Postman collection! Our Postman collection is regularly updated and contains endpoints for all Kontent.ai APIs.
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.
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.
We offer the following SDKs to help you interact with Management API. However, you don't need an SDK to use the API.
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 can authenticate your requests with either the Management API key or Subscription API key.
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.
Before the API key expires, we'll send an email notification to the API key's owner.
The API key for Management API inherits the identity of the user who generates the key.
Any API operations performed with the key will show in the content item version history and audit log as changes made by the specific user.
The API key inherits the permissions of the user who creates it. For example, if you have the permissions to only manage API keys and manage taxonomy, the API key you create allows you to use Management API and work only with the taxonomy endpoints. Using such API key with any other endpoints will result in an 403 Unauthorized
error.
The permission inheritance is dynamic. The API key permissions are directly tied to the current role of the user who creates it. If your role permissions change, the permissions of your API key change as well. No need to regenerate the API key.
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. You cannot revoke an API key without generating a new one.
The API key isn't revoked if you deactivate Management API for the project. Such API key remains valid and can be used again once Management API is activated for the project.
The scope of the API key is per project per user. When you create or regenerate an API key in one of the project's environments, this action applies to all of the project's environments.
This means you can use a single personal API key for all of 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.
The requests made to the Management API count towards the overall API calls limit set in our Fair Use Policy. For more information, see Pricing FAQ on our Kontent.ai website.
Rate 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:
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.
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.
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. |
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.
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:
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
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. To configure the asset type, you need advanced asset management. | |
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 |
file_name | string The file's name. Determined by the file referenced in the |
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 | string <uuid> The asset's internal ID. |
image_height | integer or null <int32> The image's height in pixels. Is Determined by the file referenced in the |
image_width | integer or null <int32> The image's width in pixels. Is Determined by the file referenced in the |
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 |
title | string or null <= 200 characters The asset's display name. The title can be specified when adding or upserting assets. Use this parameter to better identify and filter your assets in the UI. If not specified, the |
type | string The file's MIME type. Determined by the file referenced in the |
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": [
- {
- "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
}, - {
- "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
}
]
}
], - "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"
}, - "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
- "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",
}
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
Maximum size limit for binary files is 100 MB.
environment_id required | |
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 Example: which-brewing-fits-you-1080px.jpg |
The binary data of the file.
A file reference to the uploaded binary file.
The specified request body or the provided parameters are invalid.
// 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();
{- "id": "806ec84e-7c71-4856-9519-ee3dd3558583",
- "type": "internal"
}
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.
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. To configure the asset type, you need advanced asset management. | |
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 |
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 | |
title | string or null <= 200 characters The asset's display name. The title can be specified when adding or upserting assets. Use this parameter to better identify and filter your assets in the UI. If not specified, the |
The created asset.
The specified request was invalid.
{- "file_reference": {
- "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
- "type": "internal"
}, - "title": "Description of what the file contains",
- "folder": {
- "external_id": "sacred-treasures"
}, - "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": [
- {
- "codename": "coffee"
}, - {
- "codename": "brewing"
}
]
}
]
}
{- "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
- "file_name": "file_name.jpeg",
- "title": "Description of what the file contains",
- "size": 148636,
- "type": "image/jpeg",
- "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": [
- {
- "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
}, - {
- "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
}
]
}
], - "external_id": "custom-asset-identifier",
- "last_modified": "2017-09-12T08:29:36.1645977Z"
}
Retrieve a dynamically paginated list of assets.
A dynamically paginated list of assets.
The specified continuation token is incorrect.
// 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();
{- "assets": [
- {
- "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": [
- {
- "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
}, - {
- "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
}
]
}
], - "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"
}, - "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
- "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",
}
], - "pagination": {
- "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
}
}
Retrieve information about a single asset.
A single asset object with metadata about the asset and the referenced binary file.
The specified asset was not found.
// 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();
{- "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": [
- {
- "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
}, - {
- "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
}
]
}
], - "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"
}, - "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
- "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",
}
Update an existing asset, or add a new asset specified by external ID.
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. Requires advanced asset management. | |
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 | |
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 |
The specified asset was updated.
The specified asset was created.
The request body is invalid.
{- "title": "Coffee Brewing Techniques",
- "folder": {
- "external_id": "another-folder"
}, - "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": [
- {
- "codename": "coffee"
}, - {
- "codename": "brewing"
}
]
}
], - "file_reference": {
- "id": "fcbb12e6-66a3-4672-85d9-d502d16b8d9c",
- "type": "internal"
}
}
{- "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",
- "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": [
- {
- "id": "53a5eecb-f295-59b4-a07d-19655b6ad860"
}, - {
- "id": "3f367e4f-75b7-4b48-be3b-1136bbaf1f53"
}
]
}
], - "last_modified": "2017-09-12T08:29:36.1645977Z"
}
Delete an unused asset from an environment.
The specified asset was deleted.
The specified asset was already deleted or doesn't exist.
// 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();
{- "request_id": "00000000-0000-0000-6f12-0080000000c7",
- "error_code": 105,
- "message": "The requested asset 'fcbb12e6-66a3-4672-85d9-d502d16b8d9c' was not found."
}
Asset folders organize the assets in Kontent.ai just like folders in real life or folders on your devices.
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": "Archives",
- "external_id": "folder-with-downloadable-archives",
- "folders": [ ]
}
]
}, - {
- "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
- "name": "Legal documents",
- "external_id": "folder-documents",
- "folders": [ ]
}
], - "last_modified": "2019-08-08T08:16:24.3620957Z"
}
Retrieve an array of all asset folders.
All asset folders in the environment.
// 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();
{- "folders": [
- {
- "id": "958001d8-2228-4373-b966-5262b5b96f71",
- "name": "Downloads",
- "external_id": "folder-with-downloadable-assets",
- "folders": [
- {
- "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
- "name": "Archives",
- "external_id": "folder-with-downloadable-archives",
- "folders": [ ]
}
]
}, - {
- "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
- "name": "Legal documents",
- "external_id": "folder-documents",
- "folders": [ ]
}
], - "last_modified": "2019-08-08T08:16:24.3620957Z"
}
Add one or more asset folders. If your environment already has folders, use modify asset folders instead.
The asset folders to add.
required | Array of objects All folders within a Kontent.ai environment. | ||||||
Array
|
The created asset folders object.
The specified request body is invalid, or the environment already contains asset folders.
{- "folders": [
- {
- "id": "958001d8-2228-4373-b966-5262b5b96f71",
- "name": "Downloads",
- "external_id": "folder-with-downloadable-assets",
- "folders": [
- {
- "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
- "name": "Archives",
- "external_id": "folder-with-downloadable-archives",
- "folders": [ ]
}
]
}, - {
- "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
- "name": "Legal documents",
- "external_id": "folder-documents",
- "folders": [ ]
}
]
}
{- "folders": [
- {
- "id": "958001d8-2228-4373-b966-5262b5b96f71",
- "name": "Downloads",
- "external_id": "folder-with-downloadable-assets",
- "folders": [
- {
- "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
- "name": "Archives",
- "external_id": "folder-with-downloadable-archives",
- "folders": [ ]
}
]
}, - {
- "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
- "name": "Legal documents",
- "external_id": "folder-documents",
- "folders": [ ]
}
], - "last_modified": "2019-08-08T08:16:24.3620957Z"
}
Add, rename, or remove asset folders.
The operations you want to perform on the folders.
op required | string Specifies the operation to perform.
|
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 | |
object Reference to the existing folder before which you want to add the new folder. Note: The |
The modified asset folders.
The specified request body is invalid.
[- {
- "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"
}
}
]
{- "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": "Archives",
- "external_id": "folder-with-downloadable-archives",
- "folders": [ ]
}
]
}, - {
- "id": "9ca927b6-6e4d-4d6b-81e3-ec5e8f7772a0",
- "name": "Legal documents",
- "external_id": "folder-documents",
- "folders": [ ]
}
], - "last_modified": "2022-03-27T13:21:11.38Z"
}
With advanced asset management, you can customize images. 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.
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 |
required | object Specifies how to transform the original image asset. The image area to use for the transformation is determined by the The |
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"
}
Returns a paginated list of all renditions of the specified asset.
A dynamically paginated list of asset renditions.
The specified continuation token is incorrect.
// 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();
{- "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": {
- "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
}
}
Creates a new rendition of the specified asset.
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 |
required | object Specifies how to transform the original image asset. The image area to use for the transformation is determined by the The |
The newly created rendition.
The specified request body is invalid.
{- "transformation": {
- "mode": "rect",
- "fit": "clip",
- "custom_width": 250,
- "custom_height": 50,
- "x": 0,
- "y": 30,
- "width": 500,
- "height": 100
}, - "external_id": "hero-image-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"
}
Retrieve a rendition of the specified asset.
A single asset rendition object.
The specified asset rendition was not found.
// 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();
{- "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 of the asset.
required | object Specifies how to transform the original image asset. The image area to use for the transformation is determined by the The | ||||||||||||||||
|
The updated rendition.
The specified request body is invalid.
{- "transformation": {
- "mode": "rect",
- "fit": "clip",
- "custom_width": 250,
- "custom_height": 50,
- "x": 0,
- "y": 30,
- "width": 500,
- "height": 100
}
}
{- "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 set boundaries for your content items. Check out use cases for collections and see how to set up collections.
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 |
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"
}
Retrieve an array of all collections.
All collections in the environment.
// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Management; var client = new ManagementClient(new ManagementOptions { ApiKey = "<YOUR_API_KEY>", ProjectId = "<YOUR_PROJECT_ID>" }); var response = await client.ListCollectionsAsync();
{- "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"
}
Add, reorder, update, or remove collections.
The operations you want to perform on the collections.
op required | string Specifies the operation to perform.
|
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 | |
object Reference to the existing collection before which you want to add the new collection. Note: The |
The modified collections in the environment.
The specified request body is invalid.
[- {
- "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"
}
}
]
{- "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"
}
To manage content items, send your requests to URIs based on the following patterns:
<base_URL>/items/<content_item_id>
<base_URL>/items/codename/<content_item_codename>
<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.
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 |
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 | |
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 |
{- "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"
}, - "sitemap_locations": [ ],
- "external_id": "custom-identifier-for-my-article",
- "last_modified": "2023-04-04T13:45:30.7692802Z"
}
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.
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 |
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 | |
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. |
The content item was created.
The specified request body is invalid or the item already exists.
{- "name": "My article",
- "codename": "my_article_2",
- "type": {
- "codename": "article"
}, - "collection": {
- "id": "1b9705bf-cea7-45bb-a0f0-4451495b8cce"
}, - "external_id": "custom-item-identifier"
}
{- "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"
}
Retrieve a dynamically paginated list of content items.
A dynamically paginated list of content items.
The specified continuation token is incorrect.
// 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();
{- "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"
}, - "sitemap_locations": [ ],
- "external_id": "custom-identifier-for-my-article",
- "last_modified": "2023-04-04T13:45:30.7692802Z"
}
], - "pagination": {
- "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
}
}
Retrieve metadata about a content item.
If you want to retrieve content data, see how to retrieve language variants of a content item.
The specified content item.
The specified content item was not found.
// 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();
{- "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"
}, - "sitemap_locations": [ ],
- "external_id": "custom-identifier-for-my-article",
- "last_modified": "2023-04-04T13:45:30.7692802Z"
}
Update or create a content item.
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.
The content item to update or create.
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 |
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 | |
Array of objects Deprecated One or more references to sitemap locations. |
The updated content item.
The specified content item was created.
The specified request body is invalid.
{- "name": "My new article",
- "codename": "my_article",
- "collection": {
- "id": "00000000-0000-0000-0000-000000000000",
- "codename": "default"
}, - "sitemap_locations": [ ]
}
{- "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.
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.
The specified content item was deleted from the environment.
The specified content item was not found.
// 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();
{- "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 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 |
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 | |
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": [
- {
- "id": "f89956fd-92cc-473f-86bf-7616ffe72f5f"
}
], - "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": [
- {
- "id": "9fdd0ca7-e19d-4b83-9631-e9443f0e9d0e"
}
], - "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": {
- "id": "b14f8a4a-229d-4429-9474-4d6b9789cb95"
}, - "element": {
- "id": "e44db8df-3795-4455-95ee-d4fe10251371"
}
}, - "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"
}
}
]
}
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 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"
}
Create a new content type.
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 |
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 | |
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. |
The created content type.
The specified request body is invalid.
{- "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"
}
}
]
}
{- "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"
}
}
]
}
Retrieve a dynamically paginated list of content types.
A dynamically paginated list of content types.
The specified continuation token is incorrect.
// 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();
{- "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": [
- {
- "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": [
- {
- "id": "f89956fd-92cc-473f-86bf-7616ffe72f5f"
}
], - "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": [
- {
- "id": "9fdd0ca7-e19d-4b83-9631-e9443f0e9d0e"
}
], - "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": {
- "id": "b14f8a4a-229d-4429-9474-4d6b9789cb95"
}, - "element": {
- "id": "e44db8df-3795-4455-95ee-d4fe10251371"
}
}, - "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"
}
}
]
}
], - "pagination": {
- "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
}
}
Retrieve information about a single content type.
A content type object with metadata about the type and its elements.
The specified content type was not found.
// 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();
{- "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": [
- {
- "id": "f89956fd-92cc-473f-86bf-7616ffe72f5f"
}
], - "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": [
- {
- "id": "9fdd0ca7-e19d-4b83-9631-e9443f0e9d0e"
}
], - "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": {
- "id": "b14f8a4a-229d-4429-9474-4d6b9789cb95"
}, - "element": {
- "id": "e44db8df-3795-4455-95ee-d4fe10251371"
}
}, - "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 content types, their elements, and the configuration of specific objects.
You can modify the specified content type and its contents in three ways based on your chosen operation type (in the op
body parameter):
addInto
to add an element or content group to the content type or add an option to a multiple choice element.remove
to delete a specific element or content group from the content type or delete a specific option from a multiple choice element.replace
to change the value of a specific property of a specified object.For any operation that does not affect the content type itself, you need to include a {path_reference}
in the path
body parameter for the object you want to modify. Path references can be by ID, codename, or external ID, but take a slightly different form from references to the content type:
id:5eb3d03e-c69d-4e93-b4cc-76f453271386
codename:my_text_element
external_id:text_from_external_database
– Any special characters such as slashes (/
) need to be escaped, so the external ID my/value
would need to be added to path
as external_id:my/value
.A list of operations to perform over your content types.
op required | string Defines the operation to perform. You can use: |
path | string A string identifying where the new object or property should be added. The exact path depends on what you are trying to add and where. If you are trying to add a property to a given element, a
|
required | Array of StringArray (strings) or Asset type element (object) or Content group (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
|
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 The | |
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 The |
The modified content type.
The specified request body is invalid.
The specified content type was not found.
[- {
- "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"
}
]
{- "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": [
- {
- "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
}, - {
- "mode": "multiple",
- "options": [
- {
- "id": "523e6231-8d80-a158-3601-dffde4e64a78",
- "codename": "another_multiple_choice_option",
- "name": "Another multiple choice option"
}, - {
- "id": "d66ffa49-86ff-eeaa-c33b-e5d9eefe8b81",
- "codename": "my_other_multiple_choice_option",
- "name": "My other multiple choice option"
}
], - "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
}, - {
- "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 an unused content type.
The specified content type was deleted.
The specified type is used by content items and cannot be deleted.
The specified type was not found.
// 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();
{- "request_id": "|6374648c6c8f18449b027b68dad7808a.f72d851f_",
- "error_code": 0,
- "message": "Type 'Article (d622fc28-5202-511a-9dbf-a3ee363b6c7c)' is still used and cannot be archived."
}
The content type snippet model is structurally identical to the content type model with these exceptions:
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.
Create a new snippet.
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 required | string [ 1 .. 50 ] characters Display name of the content type snippet. |
required | Array of 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 Number type element (object) or TaxonomyTypeElement (object) or TextTypeElement (object) or Rich text type element (object) unique Elements within the snippet. |
external_id | string The content type snippet's external ID. Only present if defined when adding the snippet. |
The created content type snippet.
The specified request body is invalid.
{- "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"
}
]
}
{- "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"
}
]
}