Taxonomy
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
https://cdn.contentstack.io/v3/taxonomiesThe Get all taxonomies request retrieves all published taxonomies for the given environment.
{
"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
https://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}The Get a single taxonomy request retrieves details of a single published taxonomy.
{
"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
https://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/termsThe 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.
{
"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
https://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}The Get a single term request retrieves a specific published term within a taxonomy.
{
"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
https://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/localesThe Get a single term in all locales request retrieves all localized versions of a published term.
{
"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
https://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/descendantsThe Get descendants of a term request retrieves all descendant terms of a given term.
{
"terms": [
{
"uid": "laptops",
"name": "Laptops",
"parent_uid": "electronics",
"order": 1,
"locale": "en-us"
}
]
}Get ancestors of a term
https://cdn.contentstack.io/v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/ancestorsThe Get ancestors of a term request retrieves all ancestor terms of a given term up to the root.
{
"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
https://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
}
}
]
}{
"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"
}
}
}
}
]
}