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 · read-only · uuid

The content item's internal ID.

name

required · string · 1-200 chars

The content item's display name.

codename

string · 1-60 chars

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.

type

required · nestedSchema

Reference to the item's content type.

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

collection

object

Reference to a specific object in the environment.

Show child attributes

spaces[]

array · read-only

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.

Show child attributes

sitemap_locations[]

array · unique items

Deprecated

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

Show child attributes

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 · read-only · 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.

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",
    "codename": "default"
  },
  "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

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.

POST

https://manage.kontent.ai/v2/projects/{environment_id}/items

Request

Path parameters

environment_id

required · string

Identifies your environment.

Body schema

Application/json

The content item to be added.

name

required · string · 1-200 chars

The content item's display name.

codename

string · 1-60 chars

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.

type

required · nestedSchema

Reference to the item's content type.

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

collection

object

Reference to a specific object in the environment.

Show child attributes

sitemap_locations[]

array · unique items

Deprecated

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

Show child attributes

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.

Request samples

Payload
TypeScript
C#
cURL

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

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .addContentItem()
  .withData({
    name: 'On Roasts',
    codename: 'my_article_my_article',
    type: {
      codename: 'article',
    },
    collection: {
      codename: 'default',
    },
    external_id: '59713',
  })
  .toPromise();

Response

Status (201)

The content item was created.

id

string · read-only · uuid

The content item's internal ID.

name

required · string · 1-200 chars

The content item's display name.

codename

string · 1-60 chars

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.

type

required · nestedSchema

Reference to the item's content type.

type

id

string · uuid

The referenced object's internal ID.

collection

object

Reference to a specific object in the environment.

Show child attributes

spaces[]

array · read-only

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.

Show child attributes

sitemap_locations[]

array · unique items

Deprecated

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

Show child attributes

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 · read-only · 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.

Example responses

201
400

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

Retrieve a content item

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

GET

https://manage.kontent.ai/v2/projects/{environment_id}/items/{item_identifier}

Request

Path parameters

environment_id

required · string

Identifies your environment.

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

Request samples

TypeScript
C#
cURL

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

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .viewContentItem()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .toPromise();

Response

Status (200)

The specified content item.

id

string · read-only · uuid

The content item's internal ID.

name

required · string · 1-200 chars

The content item's display name.

codename

string · 1-60 chars

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.

type

required · nestedSchema

Reference to the item's content type.

type

id

string · uuid

The referenced object's internal ID.

collection

object

Reference to a specific object in the environment.

Show child attributes

spaces[]

array · read-only

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.

Show child attributes

sitemap_locations[]

array · unique items

Deprecated

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

Show child attributes

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 · read-only · 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.

Example responses

200
404

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

List content items

Retrieve a dynamically paginated list of content items.

GET

https://manage.kontent.ai/v2/projects/{environment_id}/items

Request

Path parameters

environment_id

required · string

Identifies your environment.

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.

Request samples

TypeScript
C#
cURL

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

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_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

Status (200)

A dynamically paginated list of content items.

items[]

required · array · unique items

List of content items.

Show child attributes

pagination

required · object

Information about the next page of results.

Show child attributes

Example responses

200
400

{
  "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": [
      {
        "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"
  },
  "pagination": {
    "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
    "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint"
  }
}

Upsert a content item

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.

PUT

https://manage.kontent.ai/v2/projects/{environment_id}/items/{item_identifier}

Request

Path parameters

environment_id

required · string

Identifies your environment.

item_identifier

required · string

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

Body schema

Application/json

The content item to update or create.

nestedSchema

Any of:

Update content item

Create content item

Update content item

name

required · string · 1-200 chars

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.

collection

object

Reference to a specific object in the environment.

Show child attributes

sitemap_locations[]

array

Deprecated

One or more references to sitemap locations.

Show child attributes

Request samples

TypeScript
C#
cURL

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

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

// Updates an existing content item
const response = await client
  .updateContentItem()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59713')
  .withData({
    name: 'On Roasts',
    codename: 'my_article_my_article',
  })
  .toPromise();

// Creates a new content item
const response = await client
  .upsertContentItem()
  .byItemExternalId('59713')
  .withData({
    name: 'On Roasts',
    codename: 'my_article_my_article',
    // 'type' is only required when creating a new content item
    type: 'article',
  })
  .toPromise();

Response

Status (200)

Status (201)

The updated content item.

id

string · read-only · uuid

The content item's internal ID.

name

required · string · 1-200 chars

The content item's display name.

codename

string · 1-60 chars

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.

type

required · nestedSchema

Reference to the item's content type.

type

id

string · uuid

The referenced object's internal ID.

collection

object

Reference to a specific object in the environment.

Show child attributes

spaces[]

array · read-only

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.

Show child attributes

sitemap_locations[]

array · unique items

Deprecated

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

Show child attributes

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 · read-only · 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.

Example responses

200
201
400

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

DELETE

https://manage.kontent.ai/v2/projects/{environment_id}/items/{item_identifier}

Request

Path parameters

environment_id

required · string

Identifies your environment.

item_identifier

required · string

Request samples

TypeScript
C#
cURL

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

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .deleteContentItem()
  .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474')
  // .byItemCodename('my_article')
  // .byItemExternalId('59714')
  .toPromise();

Response

Status (204)

The specified content item was deleted from the environment.

Empty response

Example responses

404

{
  "request_id": "2d2803b7-9b67-4bd8-b3d2-436aa077827f",
  "error_code": 100,
  "message": "The requested content item 'f4b3fc05-e988-4dae-9ac1-a94aba566474' was not found."
}

Content item object

id

string · read-only · uuid

The content item's internal ID.

name

required · string · 1-200 chars

The content item's display name.

codename

string · 1-60 chars

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.

type

required · nestedSchema

Reference to the item's content type.

id

string · uuid

The referenced object's internal ID.

codename

string · write-only

The referenced object's codename. The value of the codename property must meet the conditions defined in rules for codenames.

external_id

string · write-only

The referenced object’s external ID. The value of the external_id property must not contain the following characters: /, ., ;.

collection

object

Reference to a specific object in the environment.

Show child attributes

spaces[]

array · read-only

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.

Show child attributes

sitemap_locations[]

array · unique items

Deprecated

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

Show child attributes

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 · read-only · 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.

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",
    "codename": "default"
  },
  "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"
}

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { ManagementClient } from '@kontent-ai/management-sdk'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); const response = await client .addContentItem() .withData({ name: 'On Roasts', codename: 'my_article_my_article', type: { codename: 'article', }, collection: { codename: 'default', }, external_id: '59713', }) .toPromise();

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

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { ManagementClient } from '@kontent-ai/management-sdk'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); const response = await client .viewContentItem() .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474') // .byItemCodename('my_article') // .byItemExternalId('59713') .toPromise();

{ "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb", "name": "My article", "codename": "my_article", "type": { "id": "d89b6348-7cdc-444a-8e1e-adacb564f2a2" }, "collection": { "id": "00000000-0000-0000-0000-000000000000" }, "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" }

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { ManagementClient } from '@kontent-ai/management-sdk'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); // Gets the first page of results const response = await client.listContentItems().toPromise(); // Gets all pages of results // const response = await client.listContentItems() // .toAllPromise();

{ "items": { "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb", "name": "My article", "codename": "my_article", "type": { "id": "d89b6348-7cdc-444a-8e1e-adacb564f2a2" }, "collection": { "id": "00000000-0000-0000-0000-000000000000" }, "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" }, "pagination": { "continuation_token": "W3sidG9rZW4iOiIrUklEOn...", "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint" } }

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { ManagementClient } from '@kontent-ai/management-sdk'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); // Updates an existing content item const response = await client .updateContentItem() .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474') // .byItemCodename('my_article') // .byItemExternalId('59713') .withData({ name: 'On Roasts', codename: 'my_article_my_article', }) .toPromise(); // Creates a new content item const response = await client .upsertContentItem() .byItemExternalId('59713') .withData({ name: 'On Roasts', codename: 'my_article_my_article', // 'type' is only required when creating a new content item type: 'article', }) .toPromise();

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

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { ManagementClient } from '@kontent-ai/management-sdk'; const client = new ManagementClient({ environmentId: 'KONTENT_AI_ENVIRONMENT_ID', apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY', }); const response = await client .deleteContentItem() .byItemId('f4b3fc05-e988-4dae-9ac1-a94aba566474') // .byItemCodename('my_article') // .byItemExternalId('59714') .toPromise();