Management API v2 (2)

Download OpenAPI specification:Download

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

About Management API

Management API is a secure REST API that provides read and write access to your Kontent.ai projects and environments. If you'd like to manage subscriptions and users via API, use Subscription API.

Use Management API to manage your content & assets, content model, environment settings, and users.

Related paths

Making requests

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

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

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

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

Need content filtering?

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

Postman collection

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

Import the Postman collection

We recommend that you fork the Kontent.ai APIs collection. Forking lets you stay up to date by pulling updates when needed.

Once you import the collection, you can start sending requests. Make sure to use environment variables for API keys.

Use environment variables

Postman environments are sets of variables with specific values. You can use these variables everywhere in your requests in Postman.

For instance, the Kontent.ai APIs collection comes with an environment called Kontent.ai APIs sample values. The environment specifies a variable named environment_id, which is used in all requests. To get started quickly, we recommend you change the environment_id value to the ID of your own environment.

SDKs

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

Authentication

BearerAuthentication

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

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

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

API keys

You can use two kinds of Management API keys:

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

Find more about how to manage your API keys.

Expiration

The API key expiration length is set to 6 months by default. This is also the recommended expiration length.

When creating or regenerating your API keys, you can specify your preferred API key expiration length. The expiration length can vary from 1 minute to 2 years.

Email reminders before the expiration

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

  • If the expiration date is less than a day apart from the API key's creation date, the email notification is sent immediately.
  • If the expiration date is between 1–7 days apart form the API key's creation date, the email notification is sent 1 day before the expiration date.
  • If the expiration date is more than a week apart from the API key's creation date, the email notification is sent 1 week before the expiration date.

Identity

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

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

Permission

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

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

Revocation

If you regenerate your API key before its expiration date, the API key is revoked after a few minutes, and you get a new API key. For requests made with a revoked API key, you receive the 403 Unauthorized error.

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

Scope

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

This means you can use a single API key for all your project's environments. For example, if you clone an environment using the API, you can use your current API key for the cloned environment.

API limitations

API requests limit

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

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

Rate limiting

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

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

  • 10 requests per second
  • 400 requests per minute

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

These limits apply to requests made to a single environment.

Avoid parallel requests

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

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

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

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

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

Errors

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

HTTP status codes summary

Status code Description
400 Bad Request The request was not understood.

Check if your request is missing a required parameter or contains an invalid query parameter value.
401 Unauthorized The provided API key is doesn't provide access to the requested resource. The error can also occur if the API key is malformed or missing.

Try copying and  pasting your current API key to avoid typos.
403 Forbidden The provided API key is valid but doesn't provide permission for the specified resource.
404 Not Found The requested resource doesn't exist.

Try checking the resource name for typos.
405 Method Not Allowed The requested HTTP method is not supported for the specified resource.
429 Too Many Requests The rate limit for the API has been exceeded. Try your request again after a few seconds as specified in the Retry-After header.
5xx Internal Error or Service Unavailable Something went wrong on our side. Try your request again after a few seconds and use a retry policy.

Resolving errors

For troubleshooting failed requests, the API provides error messages defined in a consumable format to help you identify and fix the issue.

request_id
required
string <uuid>

The performed request's unique ID.

error_code
required
integer <int32> >= 0

The specific internal code for the type of error. Only useful for finding patterns among error requests.

message
required
string

The error message explaining why the error occurred.

Array of objects

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

{
  • "request_id": "|797b0d5e2cecaf41b17a5aa4ca1b9276.d1956d1_",
  • "error_code": 5,
  • "message": "The provided request body is invalid. See the 'validation_errors' attribute for more information and specify a valid JSON object.",
  • "validation_errors": [
    • {
      • "message": "No patch operations were provided, provide at least one operation."
      }
    ]
}

If you cannot identify and resolve an issue with your API call, you can contact us with the response status and the request ID you get in the error response.

Guidelines on handling changes

The state of the Management API may change in the future. However, the majority of the changes won't be breaking changes.

To create more robust scripts and integrations, we recommend you get familiar with the list of general changes to the API that aren't considered breaking. Make sure your app doesn't rely on a state that might change in the future. In general, the non-breaking changes include adding functionality or changes in the order of the returned data.

The following are NOT breaking changes:

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

Assets

Assets in Kontent.ai consist of a reference to a binary file and metadata describing the file. Each binary file can be referenced only by a single asset.

Binary files that are not used by any assets will not be visible in the Kontent.ai UI.

Adding assets is a 2-step process

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

Asset object

A single asset object.

Array of objects unique

The asset's descriptions for each active language.

Array of objects unique

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

The asset type can be managed only in the UI.

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

external_id
string

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

file_name
string

The file's name.

Determined by the file referenced in the file_reference property.

required
object

Points to a specific binary file that was uploaded to an environment.

object

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

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

object

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

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

id
string <uuid>

The asset's internal ID.

codename
string

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

image_height
integer or null <int32>

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

Determined by the file referenced in the file_reference property.

image_width
integer or null <int32>

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

Determined by the file referenced in the file_reference property.

last_modified
string <date-time>

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

size
integer <int32>

The file's size in bytes.

Determined by the file referenced in the file_reference property.

title
string or null <= 200 characters

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

type
string

The file's MIME type.

Determined by the file referenced in the file_reference property.

url
string

The asset's URL.

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

Upload a binary file

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

Add a new file. The file won't be visible in the UI until you add an asset referencing the uploaded file.

Adding assets is a 2-step process

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

Maximum size limit for binary files is 100 MB.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

Specifies the name of the uploaded binary file.

If the file name contains reserved characters, they must be URL-encoded. For example, the file name my file#2.png would be URL-encoded to my%20file%232.png. When used in an asset, the file then displays as my file#2.png in the UI.

For image files, include a file extension such as .png to ensure the files can be optimized using the Image transformation API.

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

Specifies the MIME type of the binary data.

Make sure the Content-type value matches the file extension specified in file_name.

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

Specifies the size of the binary file in bytes.

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

The binary data of the file.

string <binary> <= 104857600 characters
Responses
200

A file reference to the uploaded binary file.

400

The specified request body or the provided parameters are invalid.

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

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

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

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

Add an asset

post/projects/{environment_id}/assets

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

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

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

The asset to create.

Array of objects unique

The asset's descriptions for each active language.

Array of objects unique

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

The asset type can be managed only in the UI.

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

external_id
string

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

required
object

Points to a specific binary file that was uploaded to an environment.

object

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

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

object

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

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

codename
string

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

title
string or null <= 200 characters

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

Responses
201

The created asset.

400

The specified request was invalid.

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

List assets

get/projects/{environment_id}/assets

Retrieve a dynamically paginated list of assets.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

Determines the page of results to retrieve.

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

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of assets.

400

The specified continuation token is incorrect.

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

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

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

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

Retrieve an asset

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

Retrieve information about a single asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

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

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

404

The specified asset was not found.

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

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

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

Upsert an asset

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

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

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

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

New vs existing assets

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

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

The asset to update or create.

Array of objects

Asset descriptions for each active language.

Array of objects unique

Asset taxonomy elements as defined in the asset type.

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

object

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

object

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

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

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

title
string [ 1 .. 200 ] characters

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

required
object

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

codename
string

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

Responses
200

The specified asset was updated.

201

The specified asset was created.

400

The request body is invalid.

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

Delete an asset

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

Delete an unused asset from an environment.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

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

The specified asset was deleted.

404

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

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

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

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

Asset folders

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

Asset folders object

Defines all asset folders within a Kontent.ai environment.

required
Array of objects

All folders within a Kontent.ai environment.

last_modified
required
string <date-time>

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

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

Retrieve asset folders

get/projects/{environment_id}/folders

Retrieve an array of all asset folders.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

All asset folders in the environment.

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

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

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

Add asset folders

post/projects/{environment_id}/folders

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

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

The asset folders to add.

required
Array of objects

All folders within a Kontent.ai environment.

Array
external_id
string

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

folders
required
Array of objects

Any folders contained within the given folder.

name
required
string [ 1 .. 200 ] characters

The folder's name.

codename
string or null [ 1 .. 60 ] characters

The folder's codename. The codename is always returned when retrieving asset folders. If the codename is not specified when adding an asset folder, it will be generated automatically. Using the asset folder's codename is optional when you add or modify an asset folder.

Responses
201

The created asset folders object.

400

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

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

Modify asset folders

patch/projects/{environment_id}/folders

Add, rename, or remove asset folders.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

The operations you want to perform on the folders.

Array
op
required
string

Specifies the operation to perform.

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

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

required
object

The folder you want to add.

object

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

The after and before properties are mutually exclusive. If neither is specified, the object is added at the end.

object

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

The after and before properties are mutually exclusive. If neither is specified, the object is added at the end.

Responses
200

The modified asset folders.

400

The specified request body is invalid.

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

Asset renditions

Whenever you customize an image (by cropping it, for example), the customized version of the original image is saved as the image’s rendition.

Rendition defines what image transformation parameters need to be applied to the original image to get the customized image.

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

Rendition object

rendition_id
string <uuid>

The rendition's ID.

asset_id
string <uuid>

The id of the asset this rendition belongs to.

external_id
string or null

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

required
object

Specifies how to transform the original image asset.

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

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

last_modified
string <date-time>

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

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

List renditions

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

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

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

Example: fcbb12e6-66a3-4672-85d9-d502d16b8d9c
header Parameters
x-continuation
string

Determines the page of results to retrieve.

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

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of asset renditions.

400

The specified continuation token is incorrect.

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

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

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

Add a rendition

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

Creates a new rendition of the specified asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

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

Specify how to transform the original asset.

external_id
string or null

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

required
object

Specifies how to transform the original image asset.

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

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

Responses
201

The newly created rendition.

400

The specified request body is invalid.

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

Retrieve a rendition

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

Retrieve a rendition of the specified asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

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

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

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

A single asset rendition object.

404

The specified asset rendition was not found.

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

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

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

Modify a rendition

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

Modify a rendition of the asset.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

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

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

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

Specifies how to transform the original image asset.

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

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

mode
required
string

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

Allowed value Description
rect

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.

Allowed value Description
clip

Specifies the clip resize fit mode

custom_width
required
integer <int32> >= 0

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

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

custom_height
required
integer <int32> >= 0

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

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

x
required
integer <int32> >= 0

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

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

y
required
integer <int32> >= 0

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

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

width
required
integer

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

height
required
integer

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

Responses
200

The updated rendition.

400

The specified request body is invalid.

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

Collections

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

Collection object

id
string

The collection's internal ID.

name
required
string [ 1 .. 200 ] characters

The collection's name.

codename
string [ 1 .. 210 ] characters

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

external_id
string

The collection's external ID. 

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

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

List collections

get/projects/{environment_id}/collections

Retrieve an array of all collections.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

All collections in the environment.

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

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

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

Modify collections

patch/projects/{environment_id}/collections

Add, reorder, update, or remove collections.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

The operations you want to perform on the collections.

Array
op
required
string

Specifies the operation to perform.

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

The collection you want to add.

object

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

The after and before properties are mutually exclusive. If neither is specified, the object is added at the end.

object

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

The after and before properties are mutually exclusive. If neither is specified, the object is added at the end.

Responses
200

The modified collections in the environment.

400

The specified request body is invalid.

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

Content items

To manage content items, send your requests to URIs based on the following patterns:

  • Using internal IDs: <base_URL>/items/<content_item_id>
  • Using codenames: <base_URL>/items/codename/<content_item_codename>
  • Using external IDs: <base_URL>/items/external-id/<content_item_external_identifier>

To retrieve language variants of a specific content item, you can list the variants by specifying the internal ID, codename, or external ID of the content item.

Content item object

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

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

id
string <uuid>

The content item's internal ID.

name
required
string [ 1 .. 200 ] characters

The content item's display name.

codename
string [ 1 .. 60 ] characters

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

required
object

Reference to the item's content type.

object

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

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

Array of objects >= 0 items

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

Array of objects unique
Deprecated

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

external_id
string

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

External IDs cannot be upserted into exisiting items.

last_modified
string <date-time>

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

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

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

Add a content item

post/projects/{environment_id}/items

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

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

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

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

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

The content item to be added.

name
required
string [ 1 .. 200 ] characters

The content item's display name.

codename
string [ 1 .. 60 ] characters

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

required
object

Reference to the item's content type.

object

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

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

Array of objects unique
Deprecated

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

external_id
string

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

External IDs cannot be upserted into exisiting items.

Responses
201

The content item was created.

400

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

Request samples
application/json
{
  • "name": "My article",
  • "codename": "my_article_2",
  • "type": {
    • "codename": "article"
    },
  • "collection": {
    • "id": "1b9705bf-cea7-45bb-a0f0-4451495b8cce"
    },
  • "spaces": [
    • {
      • "id": "dcbf90fb-7135-4465-8102-b3e739821ed8"
      },
    • {
      • "id": "39efe8a4-23d2-4d3a-8dfb-07789668474f"
      }
    ],
  • "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"
    },
  • "spaces": [
    • {
      • "id": "dcbf90fb-7135-4465-8102-b3e739821ed8"
      },
    • {
      • "id": "39efe8a4-23d2-4d3a-8dfb-07789668474f"
      }
    ],
  • "sitemap_locations": [ ],
  • "external_id": "custom-item-identifier",
  • "last_modified": "2020-04-04T13:45:30.7692802Z"
}

List content items

get/projects/{environment_id}/items

Retrieve a dynamically paginated list of content items.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

Determines the page of results to retrieve.

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

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of content items.

400

The specified continuation token is incorrect.

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

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

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

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

Retrieve a content item

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

Retrieve metadata about a content item.

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

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

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

The specified content item.

404

The specified content item was not found.

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

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

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

Upsert a content item

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

Update or create a content item.

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

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

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

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

External IDs

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

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

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

The content item to update or create.

Any of:

The content item to update.

name
required
string [ 1 .. 200 ] characters

The content item's display name.

codename
string

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

object

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

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

Array of objects
Deprecated

One or more references to sitemap locations.

Responses
200

The updated content item.

201

The specified content item was created.

400

The specified request body is invalid.

Request samples
application/json
{
  • "name": "My new article",
  • "codename": "my_article",
  • "collection": {
    • "id": "00000000-0000-0000-0000-000000000000",
    • "codename": "default"
    },
  • "sitemap_locations": [ ]
}
Response samples
application/json
{
  • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
  • "name": "My new article",
  • "codename": "my_article",
  • "type": {
    • "id": "b7aa4a53-d9b1-48cf-b7a6-ed0b182c4b89"
    },
  • "collection": {
    • "id": "00000000-0000-0000-0000-000000000000"
    },
  • "spaces": [
    • {
      • "id": "dcbf90fb-7135-4465-8102-b3e739821ed8"
      },
    • {
      • "id": "39efe8a4-23d2-4d3a-8dfb-07789668474f"
      }
    ],
  • "sitemap_locations": [ ],
  • "last_modified": "2020-04-04T13:45:30.7692802Z"
}

Delete a content item

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

Delete a content item.

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

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

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

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

The specified content item was deleted from the environment.

404

The specified content item was not found.

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

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

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

Content types

Content type object

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

id
string <uuid>

The content type's internal ID.

codename
string [ 1 .. 60 ] characters

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

external_id
string

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

last_modified
string <date-time>

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

name
required
string [ 1 .. 50 ] characters

The content type's display name.

Array of objects

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

required
Array of Asset element in type (object) or Content type snippet element in type (object) or Custom element in type (object) or Date & time element in type (object) or Guidelines element in type (object) or Linked items element in type (object) or Multiple choice element in type (object) or Number element in type (object) or Rich text element in type (object) or Subpages element in type (object) or Taxonomy element in type (object) or Text element in type (object) or URL slug element in type (object) >= 0 items unique

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

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

Content group object

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

id
string <uuid>

The content group's internal ID.

name
required
string [ 1 .. 50 ] characters

The content group's display name.

codename
string [ 1 .. 60 ] characters

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

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

external_id
string

The content group's external ID.

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

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

Add a content type

post/projects/{environment_id}/types

Create a new content type.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

The content type to be added.

codename
string [ 1 .. 60 ] characters

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

external_id
string

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

name
required
string [ 1 .. 50 ] characters

The content type's display name.

Array of objects

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

required
Array of Asset element in type (object) or Content type snippet element in type (object) or Custom element in type (object) or Date & time element in type (object) or Guidelines element in type (object) or Linked items element in type (object) or Multiple choice element in type (object) or Number element in type (object) or Rich text element in type (object) or Subpages element in type (object) or Taxonomy element in type (object) or Text element in type (object) or URL slug element in type (object) >= 0 items unique

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

Responses
201

The created content type.

400

The specified request body is invalid.

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

List content types

get/projects/{environment_id}/types

Retrieve a dynamically paginated list of content types.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

Determines the page of results to retrieve.

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

Example: W3sidG9rZW4iOiIrUklEOn...
Responses
200

A dynamically paginated list of content types.

400

The specified continuation token is incorrect.

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

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

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

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

Retrieve a content type

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

Retrieve information about a single content type.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

Responses
200

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

404

The specified content type was not found.

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

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

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

Modify a content type

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

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

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

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

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

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

Identifies your environment.

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

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

Request Body schema: application/json
required

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

Array
op
required
string

Specifies the operation to perform.

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

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

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

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

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

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

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

The after and before properties are mutually exclusive. If neither is specified, the object is added at the end.

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 after and before properties are mutually exclusive. If neither is specified, the object is added at the end.

Responses
200

The modified content type.

400

The specified request body is invalid.

404

The specified content type was not found.

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

Delete a content type

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

Delete an unused content type.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

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

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

Responses