Taxonomy groups

Taxonomies are a versatile tool for categorizing and organizing your content. Learn more about the use cases for taxonomies and see how to retrieve content tagged with a specific taxonomy term.

Taxonomy group object

The taxonomy group object contains all information about your taxonomy group, such as its metadata and a collection of its taxonomy terms.

codename

string · 1-60 chars

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

external_id

string

The taxonomy group's external ID.

Only present if specified when creating the taxonomy group via API.

id

string · read-only · uuid

The taxonomy group's internal ID.

last_modified

string · read-only · date-time

ISO-8601

formatted date/time of the last change to the taxonomy group or its terms.

name

required · string · 1-50 chars

The taxonomy group's display name.

terms[]

array

All terms in the taxonomy group.

The number of terms which can be set within a taxonomy group is limited to 1000.

Show child attributes

JSON

{
  "codename": "categories",
  "external_id": "my-little-taxopony",
  "id": "bef9dd62-a3b8-4146-83e4-33be707899b4",
  "last_modified": "2020-11-14T14:05:43.9190528Z",
  "name": "Categories",
  "terms": {
    "codename": "technology",
    "external_id": "custom-term-identifier",
    "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a",
    "name": "Technology",
    "terms": []
  }
}

Add a taxonomy group

Create a new taxonomy group.

POST

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

Request

Path parameters

environment_id

required · string

Identifies your environment.

Body schema

Application/json

The taxonomy group to add.

codename

string · 1-60 chars

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

external_id

string

The taxonomy group's external ID.

Only present if specified when creating the taxonomy group via API.

name

required · string · 1-50 chars

The taxonomy group's display name.

terms[]

array

All terms in the taxonomy group.

The number of terms which can be set within a taxonomy group is limited to 1000.

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',
});

const response = await client
  .addTaxonomy()
  .withData({
    name: 'Personas',
    externalId: 'Tax-Group-123',
    codename: 'people',
    terms: [
      {
        name: 'Coffee expert',
        externalId: 'Tax-term-456',
        codename: 'expert',
        terms: [
          {
            name: 'Barista',
            externalId: 'Tax-term-789',
          },
          {
            name: 'Cafe owner',
            externalId: 'Tax-term-101',
          },
        ],
      },
      {
        name: 'Coffee enthusiast',
        codename: 'enthusiast',
        externalId: 'Tax-term-112',
        terms: [
          {
            name: 'Coffee lover',
            codename: 'lover',
            externalId: 'Tax-term-131',
          },
          {
            name: 'Coffee blogger',
            codename: 'blogger',
            externalId: 'Tax-term-145',
          },
        ],
      },
    ],
  })
  .toPromise();

Response

Status (201)

The added taxonomy group.

codename

string · 1-60 chars

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

external_id

string

The taxonomy group's external ID.

Only present if specified when creating the taxonomy group via API.

id

string · read-only · uuid

The taxonomy group's internal ID.

last_modified

string · read-only · date-time

ISO-8601

formatted date/time of the last change to the taxonomy group or its terms.

name

required · string · 1-50 chars

The taxonomy group's display name.

terms[]

array

All terms in the taxonomy group.

The number of terms which can be set within a taxonomy group is limited to 1000.

Show child attributes

Example responses

201
400

{
  "codename": "categories",
  "external_id": "my-little-taxopony",
  "id": "bef9dd62-a3b8-4146-83e4-33be707899b4",
  "last_modified": "2020-11-14T14:05:43.9190528Z",
  "name": "Categories",
  "terms": {
    "codename": "technology",
    "external_id": "custom-term-identifier",
    "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a",
    "name": "Technology",
    "terms": []
  }
}

Retrieve a taxonomy group

Retrieve a taxonomy group.

GET

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

Request

Path parameters

environment_id

required · string

Identifies your environment.

taxonomy_group_identifier

required · string

The identifier of a specific taxonomy group. You can specify a taxonomy group by its internal ID (e.g., 0be13600-e57c-577d-8108-c8d860330985), external ID (e.g., external-id/Tax-Group-123), or codename {e.g., codename/personas).

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
  .getTaxonomy()
  .byTaxonomyCodename('categories')
  // .byTaxonomyID('bef9dd62-a3b8-4146-83e4-33be707899b4')
  // .byTaxonomyExternalID('my-little-taxopony')
  .toPromise();

Response

Status (200)

A single taxonomy group with metadata.

codename

string · 1-60 chars

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

external_id

string

The taxonomy group's external ID.

Only present if specified when creating the taxonomy group via API.

id

string · read-only · uuid

The taxonomy group's internal ID.

last_modified

string · read-only · date-time

ISO-8601

formatted date/time of the last change to the taxonomy group or its terms.

name

required · string · 1-50 chars

The taxonomy group's display name.

terms[]

array

All terms in the taxonomy group.

The number of terms which can be set within a taxonomy group is limited to 1000.

Show child attributes

Example responses

200
404

{
  "codename": "categories",
  "external_id": "my-little-taxopony",
  "id": "bef9dd62-a3b8-4146-83e4-33be707899b4",
  "last_modified": "2020-11-14T14:05:43.9190528Z",
  "name": "Categories",
  "terms": {
    "codename": "technology",
    "external_id": "custom-term-identifier",
    "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a",
    "name": "Technology",
    "terms": []
  }
}

List taxonomy groups

Retrieve a dynamically paginated list of taxonomy groups.

GET

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

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.listTaxonomies().toPromise();

// Gets all pages of results
// const response = await client.listTaxonomies()
//   .toAllPromise();

Response

Status (200)

A list of taxonomy groups

taxonomies[]

required · array · unique items

A list of taxonomies.

Show child attributes

pagination

required · object

Information about the next page of results.

Show child attributes

Example responses

200
400

{
  "taxonomies": {
    "codename": "categories",
    "external_id": "my-little-taxopony",
    "id": "bef9dd62-a3b8-4146-83e4-33be707899b4",
    "last_modified": "2020-11-14T14:05:43.9190528Z",
    "name": "Categories",
    "terms": {
      "codename": "technology",
      "external_id": "custom-term-identifier",
      "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a",
      "name": "Technology",
      "terms": []
    }
  },
  "pagination": {
    "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
    "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint"
  }
}

Modify a taxonomy group

Modify how existing taxonomies are set up.You can modify taxonomy groups and their taxonomy term configuration using the following operations:

addInto operation to add new objects. For example, add a taxonomy term to the taxonomy group.
move operation to reorder objects. For example, change the position of taxonomy terms.
remove operation to delete objects. For example, delete a taxonomy term from a taxonomy group.
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 taxonomy group's terms, you need to specify a path to the taxonomy term 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.

PATCH

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

Request

Path parameters

environment_id

required · string

Identifies your environment.

taxonomy_group_identifier

required · string

Body schema

Application/json

The operations to perform on the specified taxonomy group and its taxonomy terms.

array · unique items

Any of:

TaxonomyOperationAddInto

TaxonomyOperationMove

TaxonomyOperationReplace

TaxonomyOperationRemove

TaxonomyOperationAddInto

op

required · string

Specifies the operation to perform.

addInto to add new taxonomy terms
move to reorder taxonomy terms
remove to delete taxonomy terms
replace to modify taxonomy groups and their terms

reference

object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

value

required · object

The taxonomy term object contains metadata about a single taxonomy term and a collection of its descendant taxonomy terms.

Show child attributes

after

object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

before

object

Reference to a specific object in the environment.

The API uses internal IDs for referencing objects. This means that the reference objects in the API responses will always use internal IDs.

Show child attributes

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
  .modifyTaxonomy()
  .byTaxonomyId('0be13600-e57c-577d-8108-c8d860330985')
  // .byTaxonomyCodename('personas')
  // .byTaxonomyExternalId('Tax-Group-123')
  .withData([
    {
      op: 'replace',
      property_name: 'name',
      value: 'Categories',
    },
    {
      op: 'replace',
      property_name: 'codename',
      value: 'category',
    },
    {
      op: 'replace',
      reference: {
        codename: 'first_term',
      },
      property_name: 'terms',
      value: [
        {
          name: 'Second-level taxonomy term',
          codename: 'second_term',
          terms: [
            {
              name: 'Third-level taxonomy term',
            },
          ],
        },
      ],
    },
    {
      op: 'remove',
      reference: {
        external_id: 'unused-taxonomy-term',
      },
    },
    {
      op: 'addInto',
      reference: {
        codename: 'second_term',
      },
      value: {
        name: 'New taxonomy term',
        external_id: 'my-new-term',
      },
    },
  ])
  .toPromise();

Response

Status (200)

The modified taxonomy group.

codename

string · 1-60 chars

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

external_id

string

The taxonomy group's external ID.

Only present if specified when creating the taxonomy group via API.

id

string · read-only · uuid

The taxonomy group's internal ID.

last_modified

string · read-only · date-time

ISO-8601

formatted date/time of the last change to the taxonomy group or its terms.

name

required · string · 1-50 chars

The taxonomy group's display name.

terms[]

array

All terms in the taxonomy group.

The number of terms which can be set within a taxonomy group is limited to 1000.

Show child attributes

Example responses

200
400
404

{
  "last_modified": "2019-04-02T08:08:40.3083064Z",
  "id": "f30c7f72-e9ab-8832-2a57-62944a038809",
  "name": "Categories",
  "codename": "category",
  "terms": [
    {
      "id": "146c5e35-dffe-5977-b943-16f0e862af2e",
      "name": "New taxonomy term",
      "codename": "new_taxonomy_term",
      "external_id": "my-new-term",
      "terms": []
    },
    {
      "id": "012a94e4-76b4-5a5d-95ce-164577c9b5e5",
      "name": "First-level taxonomy term",
      "codename": "first_term",
      "terms": [
        {
          "id": "9b897d7b-ded7-5de1-aee1-1e90e43db747",
          "name": "Second-level taxonomy term",
          "codename": "second_term",
          "terms": [
            {
              "id": "9bee9779-a9c6-5d66-875b-aaf7093b4ac2",
              "name": "Third-level taxonomy term",
              "codename": "third_level_taxonomy_term",
              "terms": []
            }
          ]
        }
      ]
    }
  ]
}

Delete a taxonomy group

Delete a taxonomy group specified by its internal ID, codename, or external ID.If you delete a taxonomy group that is referenced in existing content items (i.e., for tagging content), the content items keep references to the deleted taxonomy term. To find the invalid references, validate your content. Then you can remove the found invalid references.

DELETE

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

Request

Path parameters

environment_id

required · string

Identifies your environment.

taxonomy_group_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
  .deleteTaxonomy()
  .byTaxonomyId('dbff8416-c4c7-45d2-b497-a4a71a5cbe30')
  // .byTaxonomyCodename('personas_222')
  // .byTaxonomyExternalId('Tax-Group-124')
  .toPromise();

Response

Status (204)

The specified taxonomy group was deleted.

Empty response

Example responses

404

{
  "request_id": "9e6a2ec1-fb8e-49af-b1bc-011960ce4e2a",
  "error_code": 107,
  "message": "The requested taxonomy was not found."
}

Taxonomy group object

The taxonomy group object contains all information about your taxonomy group, such as its metadata and a collection of its taxonomy terms.

codename

string · 1-60 chars

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

external_id

string

The taxonomy group's external ID.

Only present if specified when creating the taxonomy group via API.

id

string · read-only · uuid

The taxonomy group's internal ID.

last_modified

string · read-only · date-time

ISO-8601

formatted date/time of the last change to the taxonomy group or its terms.

name

required · string · 1-50 chars

The taxonomy group's display name.

terms[]

array

All terms in the taxonomy group.

The number of terms which can be set within a taxonomy group is limited to 1000.

Show child attributes

JSON

{
  "codename": "categories",
  "external_id": "my-little-taxopony",
  "id": "bef9dd62-a3b8-4146-83e4-33be707899b4",
  "last_modified": "2020-11-14T14:05:43.9190528Z",
  "name": "Categories",
  "terms": {
    "codename": "technology",
    "external_id": "custom-term-identifier",
    "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a",
    "name": "Technology",
    "terms": []
  }
}

// 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 .addTaxonomy() .withData({ name: 'Personas', externalId: 'Tax-Group-123', codename: 'people', terms: [ { name: 'Coffee expert', externalId: 'Tax-term-456', codename: 'expert', terms: [ { name: 'Barista', externalId: 'Tax-term-789', }, { name: 'Cafe owner', externalId: 'Tax-term-101', }, ], }, { name: 'Coffee enthusiast', codename: 'enthusiast', externalId: 'Tax-term-112', terms: [ { name: 'Coffee lover', codename: 'lover', externalId: 'Tax-term-131', }, { name: 'Coffee blogger', codename: 'blogger', externalId: 'Tax-term-145', }, ], }, ], }) .toPromise();

{ "codename": "categories", "external_id": "my-little-taxopony", "id": "bef9dd62-a3b8-4146-83e4-33be707899b4", "last_modified": "2020-11-14T14:05:43.9190528Z", "name": "Categories", "terms": { "codename": "technology", "external_id": "custom-term-identifier", "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a", "name": "Technology", "terms": [] } }

// 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 .getTaxonomy() .byTaxonomyCodename('categories') // .byTaxonomyID('bef9dd62-a3b8-4146-83e4-33be707899b4') // .byTaxonomyExternalID('my-little-taxopony') .toPromise();

// 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.listTaxonomies().toPromise(); // Gets all pages of results // const response = await client.listTaxonomies() // .toAllPromise();

{ "taxonomies": { "codename": "categories", "external_id": "my-little-taxopony", "id": "bef9dd62-a3b8-4146-83e4-33be707899b4", "last_modified": "2020-11-14T14:05:43.9190528Z", "name": "Categories", "terms": { "codename": "technology", "external_id": "custom-term-identifier", "id": "e3c04146-f5a6-49b0-ba5b-e040d126fb3a", "name": "Technology", "terms": [] } }, "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', }); const response = await client .modifyTaxonomy() .byTaxonomyId('0be13600-e57c-577d-8108-c8d860330985') // .byTaxonomyCodename('personas') // .byTaxonomyExternalId('Tax-Group-123') .withData([ { op: 'replace', property_name: 'name', value: 'Categories', }, { op: 'replace', property_name: 'codename', value: 'category', }, { op: 'replace', reference: { codename: 'first_term', }, property_name: 'terms', value: [ { name: 'Second-level taxonomy term', codename: 'second_term', terms: [ { name: 'Third-level taxonomy term', }, ], }, ], }, { op: 'remove', reference: { external_id: 'unused-taxonomy-term', }, }, { op: 'addInto', reference: { codename: 'second_term', }, value: { name: 'New taxonomy term', external_id: 'my-new-term', }, }, ]) .toPromise();

{ "last_modified": "2019-04-02T08:08:40.3083064Z", "id": "f30c7f72-e9ab-8832-2a57-62944a038809", "name": "Categories", "codename": "category", "terms": [ { "id": "146c5e35-dffe-5977-b943-16f0e862af2e", "name": "New taxonomy term", "codename": "new_taxonomy_term", "external_id": "my-new-term", "terms": [] }, { "id": "012a94e4-76b4-5a5d-95ce-164577c9b5e5", "name": "First-level taxonomy term", "codename": "first_term", "terms": [ { "id": "9b897d7b-ded7-5de1-aee1-1e90e43db747", "name": "Second-level taxonomy term", "codename": "second_term", "terms": [ { "id": "9bee9779-a9c6-5d66-875b-aaf7093b4ac2", "name": "Third-level taxonomy term", "codename": "third_level_taxonomy_term", "terms": [] } ] } ] } ] }

// 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 .deleteTaxonomy() .byTaxonomyId('dbff8416-c4c7-45d2-b497-a4a71a5cbe30') // .byTaxonomyCodename('personas_222') // .byTaxonomyExternalId('Tax-Group-124') .toPromise();