Is AI recommending you? Ask Contentstack Canoe for free
Is AI recommending your brand? Find out with Contentstack Canoe for free
Contentstack.comAcademyLogin
CS-log-dark.svgCS-log-dark.svg
  • Changelog
  • APIs
  • SDKs

Platform

  • Solution Center
  • Marketplace
  • Changelog
  • Developers & IT
  • Business users
  • Digital leaders
  • Developer Fast Track
  • Plans & Pricing

Solutions

  • Retail
  • Travel and tourism
  • Financial services
  • Technology
  • Manufacturing
  • E-commerce
  • Localization
  • Personalization
  • Portals and knowledge bases

Resources

  • Academy
  • Docs
  • Contentstack for Developers
  • Agents Start Here
  • Product updates
  • Contentstack on Contentstack
  • Blog
  • Insights and analyst reports
  • The Forrester Wave™: Digital Experience Platforms, Q4 2025
  • Webinars
  • Podcasts
  • Glossary
  • Content generative library
  • Community
  • Headless CMS
  • Composable AXP
  • Personalization
  • CDP

Customers

  • Case Studies
  • Customer Care
  • Contentstack Experience Awards
  • Customer support

Partners

  • Overview
  • Find a partner
  • Login

Company

  • About us
  • News
  • Customer support portal
  • Contact

Social

  • Facebook
  • LinkedIn
  • Instagram
  • GitHub
  • YouTube
  • Discord
  • X
LegalTermsPrivacyTrust Center

Cookie settings

Copyright © 2026 Contentstack Inc. All rights reserved.
/
  1. Home
  2. APIs
  3. Content Delivery API
  4. Taxonomy

Taxonomy

markdownView as Markdown

Taxonomy, simplifies the process of organizing content in your system, making it effortless to find and retrieve information. It allows you to arrange your web properties in a hierarchy according to your specific needs, whether it's their purpose, intended audience, or other aspects of your business.

Only published taxonomies are available through the CDA. To fetch localized taxonomy names and terms, pass the locale query parameter. By default, the response includes only the values localized in that locale. Add include_fallback=true to also return the values that are not localized, resolved through the locale fallback hierarchy of the branch. To use the fallback hierarchy of a branch other than main, pass the branch header.

Note Refer to the Taxonomy Queries section for more query filters. Taxonomy queries match entries by the taxonomy terms stored with each published entry. If a taxonomy is deleted, those entries stop matching, and restoring the taxonomy does not change that. Republish the entries, and their variants, after you restore it. For more information, refer to Delete a taxonomy.

Get all taxonomies

GEThttps://cdn.contentstack.io/v3/taxonomies

The Get all taxonomies request retrieves all published taxonomies for the given environment.

Sample Response
Status|200 OK
12345678910111213141516
{
  "taxonomies": [
    {
      "uid": "categories",
      "name": "Categories",
      "description": "All categories for products.",
      "locale": "en-us",
      "publish_details": {
        "time": "2025-09-01T13:19:28.365Z",
        "user": "blt368bfe4e50023d0e",
        "environment": "bltd7f8cacaf649b485",
        "locale": "en-us"
      }
    }
  ]
}

Get a single taxonomy

GEThttps://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}

The Get a single taxonomy request retrieves details of a single published taxonomy.

Sample Response
Status|200 OK
1234567891011121314
{
  "taxonomy": {
    "uid": "categories",
    "name": "Catégories",
    "description": "All categories for products.",
    "locale": "fr-fr",
    "publish_details": {
      "time": "2025-09-01T13:19:28.365Z",
      "user": "blt368bfe4e50023d0e",
      "environment": "bltd7f8cacaf649b485",
      "locale": "fr-fr"
    }
  }
}

Get all terms

GEThttps://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/terms

The Get all terms request retrieves all published terms in a taxonomy for the specified environment and locale.

The sample response is for a request with locale=fr-fr and include_fallback=true. The texas term is not localized in French, so it is returned in en-us.

Sample Response
Status|200 OK
123456789101112131415161718
{
  "terms": [
    {
      "uid": "california",
      "locale": "fr-fr",
      "name": "Californie",
      "taxonomy_uid": "regions",
      "depth": 2
    },
    {
      "uid": "texas",
      "locale": "en-us",
      "name": "Texas",
      "taxonomy_uid": "regions",
      "depth": 2
    }
  ]
}

Get a single term

GEThttps://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}

The Get a single term request retrieves a specific published term within a taxonomy.

Sample Response
Status|200 OK
123456789101112131415
{
  "term": {
    "uid": "gaming_laptops",
    "name": "Ordinateurs portables de jeu",
    "parent_uid": "laptops",
    "order": 1,
    "locale": "fr-fr",
    "publish_details": {
      "time": "2025-09-01T13:19:28.365Z",
      "user": "blt368bfe4e50023d0e",
      "environment": "bltd7f8cacaf649b485",
      "locale": "fr-fr"
    }
  }
}

Get a single term in all locales

GEThttps://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/locales

The Get a single term in all locales request retrieves all localized versions of a published term.

Sample Response
Status|200 OK
1234567891011121314151617181920212223242526
{
  "terms": [
    {
      "uid": "gaming_laptops",
      "name": "Gaming Laptops",
      "locale": "en-us",
      "publish_details": {
        "time": "2025-09-01T13:19:28.365Z",
        "user": "blt368bfe4e50023d0e",
        "environment": "bltd7f8cacaf649b485",
        "locale": "en-us"
      }
    },
    {
      "uid": "gaming_laptops",
      "name": "Ordinateurs Portables de Jeu",
      "locale": "fr-fr",
      "publish_details": {
        "time": "2025-09-01T13:25:00.000Z",
        "user": "blt368bfe4e50023d0e",
        "environment": "bltd7f8cacaf649b485",
        "locale": "fr-fr"
      }
    }
  ]
}

Get descendants of a term

GEThttps://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/descendants

The Get descendants of a term request retrieves all descendant terms of a given term.

Sample Response
Status|200 OK
1234567891011
{
  "terms": [
    {
      "uid": "laptops",
      "name": "Laptops",
      "parent_uid": "electronics",
      "order": 1,
      "locale": "en-us"
    }
  ]
}

Get ancestors of a term

GEThttps://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/ancestors

The Get ancestors of a term request retrieves all ancestor terms of a given term up to the root.

Sample Response
Status|200 OK
123456789101112131415161718
{
  "terms": [
    {
      "uid": "laptops",
      "name": "Laptops",
      "parent_uid": "electronics",
      "order": 1,
      "locale": "en-us"
    },
    {
      "uid": "electronics",
      "name": "Electronics",
      "parent_uid": null,
      "order": 1,
      "locale": "en-us"
    }
  ]
}

Get entries by taxonomy with variants

GEThttps://cdn.contentstack.io/v3/taxonomies/entries?query={"taxonomies.taxonomy_uid": "term_uid"}

The Get entries by taxonomy with variants request retrieves the entries that match a taxonomy query, with the specified variants applied to them.

Pass your variant UID(s) or aliases in the x-cs-variant-uid header. You can pass the aliases you get from Personalize directly, and mix them with variant UIDs in the same request. Each matching entry that has a published variant is returned with that variant applied.

Note By default you can add up to 5 variant UIDs or aliases (comma-separated) simultaneously. To increase this limit, contact support. The variant UID or alias added first takes priority and is applied to the base entry fields. Sample header request, x-cs-variant-uid: cs_personalize_0_1, cs_personalize_2_0. The API timeout for requests with entry variants is capped at 10 seconds.

Matching entries that do not have an entry variant for the variants you pass are returned as base entries.

When an alias resolves to a variant, that variant is listed in the entry's publish_details.variants object.

Note Refer to the Taxonomy Queries section for more query filters.

Error Handling

If the number of variants exceeds the configured limit:

  • The API processes only up to the allowed limit, keeping the variants added first.
  • Pass the show_errors=true query parameter to include an errors array describing the truncation.
  • If show_errors is false or not set, the errors key is omitted.

Sample response when the show_errors=true query parameter is passed and allowed variant limit is exceeded:

{
  "entries": [ ... ],
  "errors": [
    {
      "code": "VARIANT_LIMIT_EXCEEDED",
      "message": "x-cs-variant-uid should not be greater than 5",
      "details": {
        "original_count": 7,
        "unique_count": 7,
        "filtered_count": 6,
        "limit": 5,
        "applied_count": 5
      }
    }
  ]
}
Sample Response
Status|200 OK
12345678910111213141516171819202122232425262728293031
{
    "entries": [
        {
            "_version": 3,
            "locale": "en-us",
            "uid": "blt492d7ae2f81ee5fd",
            "title": "Paris deals",
            "taxonomies": [
                {
                    "taxonomy_uid": "region",
                    "term_uid": "france"
                }
            ],
            "_content_type_uid": "offers",
            "publish_details": {
                "environment": "blt0c46fa6bf0ebbc8f",
                "locale": "en-us",
                "time": "2026-10-20T11:25:12.450Z",
                "user": "blt6fe92749b66ad81a",
                "variants": {
                    "3439b92ff6b5406ab559e7e7f246a49b": {
                        "time": "2026-10-20T12:43:11.986Z",
                        "user": "blt3d9f7cdb9bffaa6a",
                        "environment": "blt0c46fa6bf0ebbc8f",
                        "locale": "en-us"
                    }
                }
            }
        }
    ]
}
Hide Parameters

Query Parameters

limitoptionalstring

Number of results to return.

Example:

5
skipoptionalstring

Number of results to skip (for pagination).

Example:

5
environmentrequiredstring

Enter the name of the environment the taxonomy is published to.

Example:

production
localeoptionalstring

Enter the code of the locale to fetch the localized taxonomy names in.

Example:

fr-fr
include_fallbackoptionalstring

Set to true to also return the taxonomies that are not localized in the requested locale, through the locale fallback hierarchy of the branch. Each taxonomy's locale field shows the locale it was returned from.

Example:

true

Headers

api_keyoptionalstring

Enter the API key of the stack.

Example:

your_stack_api_key
access_tokenoptionalstring

Enter your environment-specific delivery token. Check Authentication.

Example:

your_access_token
Hide Parameters

URL Parameters

taxonomy_uidoptionalstring

Enter the unique ID of the taxonomy you want to update. The UID of a taxonomy is unique across a stack.

Example:

categories

Query Parameters

limitoptionalstring

Number of results to return.

Example:

5
skipoptionalstring

Number of results to skip (for pagination).

Example:

5
environmentrequiredstring

Enter the name of the environment the taxonomy is published to.

Example:

production
localeoptionalstring

Enter the code of the locale to fetch the localized taxonomy name in.

Example:

fr-fr
include_fallbackoptionalstring

Set to true to return the taxonomy through the locale fallback hierarchy of the branch if it is not localized in the requested locale. Without it, a taxonomy that is not localized in the requested locale returns a 404 error.

Example:

true

Headers

api_keyoptionalstring

Enter the API key of the stack.

Example:

your_stack_api_key
access_tokenoptionalstring

Enter your environment-specific delivery token. Check Authentication.

Example:

your_access_token
Hide Parameters

URL Parameters

taxonomy_uidoptionalstring

Enter the unique ID of the taxonomy you want to update. The UID of a taxonomy is unique across a stack.

Example:

categories

Query Parameters

limitoptionalstring

Number of results to return.

Example:

5
skipoptionalstring

Number of results to skip (for pagination).

Example:

5
depthoptionalstring

Depth of term hierarchy to retrieve.

Example:

2
environmentrequiredstring

Enter the name of the environment the taxonomy is published to.

Example:

production
localeoptionalstring

Enter the code of the locale to fetch the localized term names in.

Example:

fr-fr
include_fallbackoptionalstring

Set to true to also return the terms that are not localized in the requested locale through the locale fallback hierarchy of the branch. Each item's locale field shows the locale it was returned from.

Example:

true

Headers

api_keyoptionalstring

Enter the API key of the stack.

Example:

your_stack_api_key
access_tokenoptionalstring

Enter your environment-specific delivery token. Check Authentication.

Example:

your_access_token
Hide Parameters

URL Parameters

taxonomy_uidoptionalstring

Enter the unique ID of the taxonomy you want to update. The UID of a taxonomy is unique across a stack.

Example:

categories
term_uidoptionalstring

Enter the unique ID of the term of which you want to retrieve the details. The UID of a term is unique across a stack.

Example:

gaming_laptops

Query Parameters

limitoptionalstring

Number of results to return.

Example:

5
skipoptionalstring

Number of results to skip (for pagination).

Example:

5
depthoptionalstring

Depth of term hierarchy to retrieve.

Example:

2
environmentrequiredstring

Enter the name of the environment the taxonomy is published to.

Example:

production
localeoptionalstring

Enter the code of the locale to fetch the localized term name in.

Example:

fr-fr
include_fallbackoptionalstring

Set to true to return the term through the locale fallback hierarchy of the branch if it is not localized in the requested locale. Without it, a term that is not localized in the requested locale returns a 404 error.

Example:

true

Headers

api_keyoptionalstring

Enter the API key of the stack.

Example:

your_stack_api_key
access_tokenoptionalstring

Enter your environment-specific delivery token. Check Authentication.

Example:

your_access_token
Hide Parameters

URL Parameters

taxonomy_uidoptionalstring

Enter the unique ID of the taxonomy you want to update. The UID of a taxonomy is unique across a stack.

Example:

categories
term_uidoptionalstring

Enter the unique ID of the term of which you want to retrieve the details. The UID of a term is unique across a stack.

Example:

gaming_laptops

Query Parameters

limitoptionalstring

Number of results to return.

Example:

5
skipoptionalstring

Number of results to skip (for pagination).

Example:

5
environmentrequiredstring

Enter the name of the environment the taxonomy is published to.

Example:

production

Headers

api_keyoptionalstring

Enter the API key of the stack.

Example:

your_stack_api_key
access_tokenoptionalstring

Enter your environment-specific delivery token. Check Authentication.

Example:

your_access_token
Hide Parameters

URL Parameters

taxonomy_uidoptionalstring

Enter the unique ID of the taxonomy you want to update. The UID of a taxonomy is unique across a stack.

Example:

categories
term_uidoptionalstring

Enter the unique ID of the term of which you want to retrieve the details. The UID of a term is unique across a stack.

Example:

gaming_laptops

Query Parameters

limitoptionalstring

Number of results to return.

Example:

5
skipoptionalstring

Number of results to skip (for pagination).

Example:

5
depthoptionalstring

Depth of term hierarchy to retrieve.

Example:

2
environmentrequiredstring

Enter the name of the environment the taxonomy is published to.

Example:

production
localeoptionalstring

Enter the code of the locale to fetch the descendant terms in.

Example:

fr-fr
include_fallbackoptionalstring

Set to true to also return the descendant terms that are not localized in the requested locale, through the locale fallback hierarchy of the branch.

Example:

true

Headers

api_keyoptionalstring

Enter the API key of the stack.

Example:

your_stack_api_key
access_tokenoptionalstring

Enter your environment-specific delivery token. Check Authentication.

Example:

your_access_token
Hide Parameters

URL Parameters

taxonomy_uidoptionalstring

Enter the unique ID of the taxonomy you want to update. The UID of a taxonomy is unique across a stack.

Example:

categories
term_uidoptionalstring

Enter the unique ID of the term of which you want to retrieve the details. The UID of a term is unique across a stack.

Example:

gaming_laptops

Query Parameters

limitoptionalstring

Number of results to return.

Example:

5
skipoptionalstring

Number of results to skip (for pagination).

Example:

5
depthoptionalstring

Depth of term hierarchy to retrieve.

Example:

2
environmentrequiredstring

Enter the name of the environment the taxonomy is published to.

Example:

production
localeoptionalstring

Enter the code of the locale to fetch the term and its ancestors in. The ancestors are returned in the same locale the term resolves to: if the term falls back to another locale, its ancestors are returned in that locale too.

Example:

fr-fr
include_fallbackoptionalstring

Set to true to return the term and its ancestors through the locale fallback hierarchy of the branch when they are not localized in the requested locale.

Example:

true

Headers

api_keyoptionalstring

Enter the API key of the stack.

Example:

your_stack_api_key
access_tokenoptionalstring

Enter your environment-specific delivery token. Check Authentication.

Example:

your_access_token
Hide Parameters

Query Parameters

queryoptionalstring

Provide a custom query in string format.

Example:

{"taxonomies.taxonomy_uid" : "term_uid"}
environmentoptionalstring

Enter the environment scoped to your delivery token. For example, if your delivery token is scoped to the production environment, pass the value as production.

Example:

production
localeoptionalstring

Enter the code of the locale to fetch entries in.

Example:

en-us
include_taxonomy_termsoptionalstring

Set to true to resolve the taxonomy terms in the response. Each object in an entry's taxonomies array then also carries taxonomy_name, term_name, and the locale the term name resolved in. Without this parameter, taxonomies carries only taxonomy_uid and term_uid.

Example:

true
include_fallbackoptionalstring

Set to true to return entries and resolve taxonomy terms through the locale fallback hierarchy of the branch when they are not localized in the requested locale.

Example:

true
show_errorsoptionalstring

Pass this as true to include the errors array in the response.

Example:

true

Headers

api_keyrequiredstring

Enter the API key of your stack.

Example:

blt02f7b45378b008ee
access_tokenrequiredstring

Enter the environment-specific delivery token of your stack. Check Authentication.

Example:

cs5b69faf35efdebd91d08bcf4
x-cs-variant-uidrequiredstring

Enter one or more variant UIDs or Personalize variant aliases, separated by commas. You can mix UIDs and aliases in the same request.

Example:

cs_personalize_0_1, cs_personalize_2_0
branchoptionalstring

Enter your branch unique ID.

Example:

main