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.

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.

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.

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.

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.

pagination

required · object

Information about the next page of results.

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

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

Accepted values:

addInto, move, replace, remove

reference

object

Reference to an existing taxonomy term under which you want to add the new term.If you need to add taxonomy terms to the root of the taxonomy group, don't specify a reference.

value

required · object

The taxonomy term object you want to add.

after

object

An optional reference to the taxonomy term after which you want to add the new taxonomy term.For example, to add a term after an existing "Categories" term, you can set after to {codename: categories}.

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

before

object

An optional reference to the taxonomy term before which you want to add the new taxonomy term.For example, to add a term before the existing "Categories" term, you can set before to {codename: categories}.

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

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.

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.

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();