Collections

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

Collection object

id

string · read-only

The collection's internal ID.

name

required · string · 1-200 chars

The collection's name.

codename

string · 1-210 chars

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.

JSON

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

List collections

Retrieve an array of all collections.

GET

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

Request

Path parameters

environment_id

required · string

Identifies your environment.

Request samples

C#
cURL

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

var client = new ManagementClient(new ManagementOptions
{
    ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY",
    EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID"
});

var response = await client.ListCollectionsAsync();

Response

Status (200)

All collections in the environment.

collections[]

required · array

All collections within a project.

Show child attributes

last_modified

required · string · read-only · date-time

The ISO-8601

formatted date and time of the last change to content collections. This property can be null if the collections were not changed yet.

Example responses

200

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

Add, reorder, update, or remove collections.

PATCH

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

Request

Path parameters

environment_id

required · string

Identifies your environment.

Body schema

Application/json

The operations you want to perform on the collections.

array · unique items

Any of:

CollectionOperationAddInto

CollectionOperationMove

CollectionOperationRemove

CollectionOperationReplace

CollectionOperationAddInto

op

required · string · write-only

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)

value

required · nestedSchema

The collection you want to add.

name

required · string · 1-200 chars

The collection's name.

codename

string · 1-210 chars

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.

after

nestedSchema

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.

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: /, ., ;.

before

nestedSchema

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.

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: /, ., ;.

Request samples

Payload
C#
cURL

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

Status (200)

The modified collections in the environment.

collections[]

required · array

All collections within a project.

Show child attributes

last_modified

required · string · read-only · date-time

The ISO-8601

formatted date and time of the last change to content collections. This property can be null if the collections were not changed yet.

Example responses

200
400

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

Collection object

id

string · read-only

The collection's internal ID.

name

required · string · 1-200 chars

The collection's name.

codename

string · 1-210 chars

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.

JSON

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

// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Management; var client = new ManagementClient(new ManagementOptions { ApiKey = "KONTENT_AI_MANAGEMENT_API_KEY", EnvironmentId = "KONTENT_AI_ENVIRONMENT_ID" }); var response = await client.ListCollectionsAsync();

{ "collections": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "Default", "codename": "default" }, { "id": "56ddd0f8-d3a3-5e36-9ccb-80dbe77aed23", "external_id": "second_external_id", "name": "Second collection", "codename": "second_collection" } ], "last_modified": "2021-03-04T08:16:24.3620957Z" }

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