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. If you'd like to manage subscriptions and users via API, use Subscription API.

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

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

curl --request GET 
  --url https://manage.kontent.ai/v2/projects/<YOUR_PROJECT_ID>/items 
  --header 'Authorization: Bearer <YOUR_API_KEY>' 
  --header 'x-continuation: <continuation_token>' 
  --header 'Content-type: application/json'

Need content filtering?

If you need to filter content and deliver it to your apps, we recommend using Delivery REST API or Delivery GraphQL API.

Postman collection

Try the Kontent.ai APIs with Postman! 📫 The Postman collection is regularly updated and contains endpoints for all Kontent.ai APIs, just like you see in the API references.

SDKs

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

Authentication

Bearer authentication

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.

  • Management API key – Find it in Kontent.ai > Project settings > API keys.
    • Limited to users with the Manage APIs permission.
    • Provides access to a single Kontent.ai project via API. You will need a different Management API key for each of your projects.
    • Dynamically inherits the permissions of the user who creates it.
    • Can be used with Management API endpoints that get or modify objects within a single project.
  • Subscription API key – Find it in Kontent.ai > Subscriptions > Your subscription > Subscription API.
    • Limited to subscription admins.
    • Provides access to the projects and subscriptions that the subscription admin has access to.
    • Dynamically inherits the permissions of the user who creates it.
    • Can be used with all Management API and Subscription API endpoints.
Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "<YOUR_API_KEY>"

API keys

Regenerate API keys you created before Jan 23, 2023

On Jan 23, 2023, we've introduced new personal API keys. Make sure to use the new API keys in your existing apps.

The API keys created before Jan 23, 2023 have been deprecated and will stop working on April 30, 2023.

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.

Expiration reminder

5 days before the API key's expiration date, we'll send a notification email to users with the Manage APIs permission.

Identity

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.

Permission

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.

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

Scope

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.

API limitations

API requests limit

The requests made to the Management API count towards the overall API calls limit set in our Fair Use Policy. For more information, see Pricing FAQ on our Kontent.ai website.

Rate limiting

Rate limits specify the number of requests you or your application can make to the Management API within a specific time window. There are two separate time windows, second and minute, allowing a different number of requests each.

By default, the Management API enforces the following rate limits:

  • 10 requests per second
  • 400 requests per minute

The scope of these rate limits is per environment. Requests made with multiple API keys from a single environment count against a single rate limit.

These limits apply to requests made to a single environment.

Avoid parallel requests

We strongly advise against making multiple requests to the API in parallel. Doing so may cause unpredictable behavior and lead to inconsistencies in your content. We recommend that you wait for each request to finish before sending another one.

When you reach the limit of a specific time window, the API will reject the request and respond with the 429 HTTP error.

{
    "request_id": "80000004-0002-fd00-b63f-84710c7967bb",
    "error_code": 10000,
    "message": "API rate limit exceeded. Please retry your request later."
}

The error response will include the Retry-After header that tells you how many seconds you need to wait before attempting further requests. Each failed request is perfectly safe to retry.

If you begin to receive 429 HTTP errors, reduce the frequency of your requests.

Errors

The API returns standard HTTP status codes to indicate the success or failure of a request. In general, status codes in the 2xx range indicate a successful request, status codes in the 4xx range indicate errors caused by an incorrect input (for example, providing incorrect API key), and status codes in the 5xx range indicate an error on our side.

HTTP status codes summary

Status code Description
400 Bad Request The request was not understood. Check your request for a missing required parameter or an invalid query parameter value.
401 Unauthorized The provided API key expired, is in the wrong format, or is missing. Try copying and using the current API key for your project.
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 won't be breaking changes. To help you create more robust scripts and integrations, we've prepared a list of general changes to the API that we don't consider breaking. We recommend you read through the list to ensure you don't rely on a state that might change in the future.

In general, the non-breaking changes include adding functionality or changes in order of the returned data. More specifically, the following are NOT breaking changes:

  • General:
    • Add a new endpoint.
    • Change the API behavior to fix a bug in the service.
    • Change rate limitation.
    • Change error message text.
  • Responses:
    • Add a new property to JSON objects.
    • Change the order of JSON object properties.
    • Add a new type of element for content types or snippets.
    • Add a new HTML element to rich text elements.
    • Add a new attribute to HTML element in rich text elements.
    • Add a new value to HTML element attribute in rich text elements.
    • Change the order of HTML element attributes in rich text elements.
    • Represent some characters as HTML entities.
    • Add a new response header.
    • Add a body to a request that contained none.
  • Requests:
    • Add a new optional property to JSON objects.
    • Add a new optional attribute to HTML element in rich text elements.
    • Add a new value to the HTML element attribute in rich text elements.
    • Add a new optional request header.
    • Add a new optional query string parameter.
    • Add an optional body to request that contained none.

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 – after uploading, you get a file reference to uploaded file.
  2. Create a new asset – use the file reference to link the new asset with the 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. 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 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 your project.

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

id
string <uuid>

The asset's internal ID.

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 this parameter 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"
    },
  • "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",
}

Upload a binary file

post/projects/{project_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 – after uploading, you get a file reference to uploaded file.
  2. Create a new asset – use the file reference to link the new asset with the file.

Maximum size limit for binary files is 100 MB.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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

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({
  projectId: '<YOUR_PROJECT_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/{project_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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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 external_id property is not present.

required
object

Points to a specific binary file uploaded to your project.

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

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 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"
    },
  • "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",
  • "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/{project_id}/assets

Retrieve a dynamically paginated list of assets.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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({
  projectId: '<YOUR_PROJECT_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"
        },
      • "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": {}
}

Retrieve an asset

get/projects/{project_id}/assets/{asset_identifier}

Retrieve information about a single asset.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c) 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({
  projectId: '<YOUR_PROJECT_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"
    },
  • "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",
}

Upsert an asset

put/projects/{project_id}/assets/{asset_identifier}

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

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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 {"id" : "00000000-0000-0000-0000-000000000000"}.

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 binary file uploaded to your project. 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.

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"
    },
  • "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",
  • "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/{project_id}/assets/{asset_identifier}

Delete an unused asset from your project.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c) 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 from the project.

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({
  projectId: '<YOUR_PROJECT_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 are ways for you to organize the assets in your projects. The asset folders object contains all folders within a given project.

Asset folders object

All folders within a project.

required
Array of objects

All folders within a project.

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/{project_id}/folders

Retrieve an array of all asset folders in your project.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

All asset folders in the project.

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({
  projectId: '<YOUR_PROJECT_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/{project_id}/folders

Add one or more asset folders to a project. If your project already has folders, use modify asset folders instead.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

The asset folders to add.

required
Array of objects

All folders within a project.

Array
external_id
string

The folder's external ID. Only present if specified 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 project already has 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/{project_id}/folders

Add, rename, or remove asset folders.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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 folders in the project.

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

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 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/{project_id}/assets/{asset_identifier}/renditions

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

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c) 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({
  projectId: '<YOUR_PROJECT_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/{project_id}/assets/{asset_identifier}/renditions

Creates a new rendition of the specified asset.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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

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

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/{project_id}/assets/{asset_identifier}/renditions/{rendition_identifier}

Retrieve a rendition of the specified asset.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c) 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({
  projectId: '<YOUR_PROJECT_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/{project_id}/assets/{asset_identifier}/renditions/{rendition_identifier}

Modify a rendition of the asset.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c) 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 use cases for collections and see how to set up collections for your project.

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/{project_id}/collections

Retrieve an array of all collections in your project.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

All collections in the project.

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_PROJECT_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/{project_id}/collections

Add, reorder, update, or remove collections.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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

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. The content item object does not store the content itself. The content for each language variant of a content item is saved in language variants, with each content item having as many variants as there are active languages in your project.

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 unique
Deprecated

The content item's location (or locations) in the project 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"
    },
  • "sitemap_locations": [ ],
  • "external_id": "custom-identifier-for-my-article",
  • "last_modified": "2023-04-04T13:45:30.7692802Z"
}

Add a content item

post/projects/{project_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 projects with just one 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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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 project 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/{project_id}/items

Retrieve a dynamically paginated list of content items.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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({
  projectId: '<YOUR_PROJECT_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"
        },
      • "sitemap_locations": [ ],
      • "external_id": "custom-identifier-for-my-article",
      • "last_modified": "2023-04-04T13:45:30.7692802Z"
      }
    ],
  • "pagination": {}
}

Retrieve a content item

get/projects/{project_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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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({
  projectId: '<YOUR_PROJECT_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"
    },
  • "sitemap_locations": [ ],
  • "external_id": "custom-identifier-for-my-article",
  • "last_modified": "2023-04-04T13:45:30.7692802Z"
}

Upsert a content item

put/projects/{project_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 projects with just one language.

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

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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/{project_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: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

404

The specified content item 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({
  projectId: '<YOUR_PROJECT_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 type contains information about the structure of your content. The content type object defines the elements that your content items or components can consist of. To make authoring experience more pleasant, you can put your elements in separate 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

Content groups help you organize the elements within a content type.

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/{project_id}/types

Create a new content type.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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/{project_id}/types

Retrieve a dynamically paginated list of content types.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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({
  projectId: '<YOUR_PROJECT_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/{project_id}/types/{type_identifier}

Retrieve information about a single content type.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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({
  projectId: '<YOUR_PROJECT_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/{project_id}/types/{type_identifier}

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.
SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

A list of operations to perform over your project's content types.

Array
op
required
string

Defines the operation to perform. You can use: addInto to add new objects, remove to delete objects, or replace to modify specific properties.

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 {path_reference} is needed for that element.

  1. To add a new element, set path to: /elements.
  2. To add a new content group, set path to: /content_groups.
  3. To add an allowed content type to a rich text or linked items element, set path to: /elements/{path_reference}/allowed_content_types.
  4. To add an allowed element to a custom element, set path to: /elements/{path_reference}/allowed_elements.
  5. To add a new multiple choice option, set path to: /elements/{path_reference}/options.
  6. 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 ContentGroup (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:

  1. To add a new element, use a content element object.
  2. To add a new content group, use a content group object.
  3. 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.
  4. To add an allowed element to a custom element, use a reference object that points to the specific element.
  5. To add an option to a multiple choice element, use an option object.
  6. 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"
    }
]
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": [
    • {
      • "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": [
        • {
          },
        • {
          }
        ],
      • "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 a content type

delete/projects/{project_id}/types/{type_identifier}

Delete an unused content type.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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 type was deleted from the project.

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({
  projectId: '<YOUR_PROJECT_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/{project_id}/snippets

Create a new snippet.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

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

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

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/{project_id}/snippets

Retrieve a dynamically paginated list of content type snippets.

SecurityHTTP: Bearer authentication
Request
path Parameters
project_id
required
string

Identifies your project.

If you're using environments, the project ID becomes environment ID and specifies one of the project's environments.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
header Parameters