Taxonomy
Taxonomy
A taxonomy arranges the content of a stack into a hierarchy of terms, for example vehicles with the child terms cars and bikes. The Taxonomy class manages the taxonomies of one stack through the Content Management API (CMA). Use this class to
- list, create and import the taxonomies of a stack
- read, update, localize, export and delete one taxonomy
- publish and unpublish taxonomies to environments and locales
- open the terms of one taxonomy through the Terms class
Call the taxonomy method of a Stack object to get an object, for example stack.taxonomy('<TAXONOMY_UID>').
Instance State
- Call taxonomy() without a UID to work with all the taxonomies of the stack, for example create and publish.
- Call taxonomy('<TAXONOMY_UID>') to work with one taxonomy, for example fetch and terms.
- Each form has only its own methods, except the three header methods. fetch is undefined on taxonomy(), and publish is undefined on taxonomy('<TAXONOMY_UID>'), so calling the wrong one throws TypeError.
- The objects that create, import, fetch, update, localize and query().find() return are the single-taxonomy form.
Warning taxonomy('') returns the collection form, because the SDK treats an empty string as no UID. Check the UID before you build the object.
Class-Level Notes
Branch scoping.
- When you create the stack with branch_uid, every request from this class sends the branch header. The API uses the branch for its locale fallback hierarchy, as Get all taxonomies describes.
Headers.
- Every request sends the headers of this object, which start as the headers of the stack. Change them for this object only with addHeader, addHeaderDict and removeHeader.
Locales.
- Methods that read or change one language version of a taxonomy take the locale code as a locale query parameter. Without it, the API works with the master locale.
Rate limiting and retry.
- This SDK automatically retries on 429 with configurable delay and attempt limits.
Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Unlocalize a taxonomy | No | The SDK has no method for Unlocalize a taxonomy |
| Publish single terms | No | The API publishes a taxonomy together with all its terms |
| Import from a file in a browser | No | import reads a file path with the Node.js fs module |
Method Index
Work with the taxonomies of a stack. Available on stack.taxonomy().
| Method Name | Returns | Description |
|---|---|---|
| query | A query for taxonomies, sent when you call find(), findOne() or count(). | Builds a taxonomy query. |
| create | The new taxonomy. | Creates a taxonomy. |
| import | The imported taxonomy. | Imports a taxonomy from a JSON or CSV file. |
Publish taxonomies. Available on stack.taxonomy().
| Method Name | Returns | Description |
|---|---|---|
| publish | The API response with a notice and the job ID. | Publishes taxonomies to environments and locales. |
| unpublish | The API response with a notice and the job ID. | Unpublishes taxonomies from environments and locales. |
Read and change one taxonomy. Available on stack.taxonomy('<TAXONOMY_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested taxonomy. | Retrieves one taxonomy. |
| update | The updated taxonomy. | Saves the fields of this object. |
| delete | The status and status text of the API response. | Deletes the taxonomy and its terms. |
| export | The exported taxonomy and its terms. | Exports the taxonomy as JSON or CSV. |
| locales | The API response with the language versions of the taxonomy. | Lists the language versions of the taxonomy. |
| localize | The localized taxonomy. | Adds a language version of the taxonomy. |
| terms | A new terms object. | Opens the terms of the taxonomy. |
Set request headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same taxonomy, for chaining. | Adds one request header. |
| addHeaderDict | The same taxonomy, for chaining. | Adds several request headers. |
| removeHeader | The same taxonomy, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below creates a taxonomy, adds a term to it, and lists the terms of the new taxonomy.
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const taxonomy = await stack.taxonomy().create({
taxonomy: { uid: 'docs_test_vehicles', name: 'docs-test-vehicles' }
})
await taxonomy.terms().create({
term: { uid: 'cars', name: 'Cars', parent_uid: null, order: 1 }
})
const result = await stack.taxonomy(taxonomy.uid).terms().query().find()
for (const term of result.items) {
console.log(term.uid, term.name)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Methods
Each method of the Taxonomy class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one header to every request that this taxonomy object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
Returns: Taxonomy. The same taxonomy, for chaining.
Validation
- There is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeader sends no request.
- Until its first header change, this object shares the header map of the stack, so a header that you add to the stack also reaches it. The first change copies that map. From then on, changes apply to this object only, not to the stack or to its other objects.
- Every request method of this object sends its headers. A key that the object already holds gets the new value.
- terms passes the headers of this object on to the Terms object it returns. Change the headers first, then call it.
Example
Basic usage: tag the requests of one taxonomy object
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const taxonomy = stack.taxonomy('<TAXONOMY_UID>').addHeader('x-request-id', 'docs-123')
// Every request this object sends from now on carries the header
console.log(taxonomy.stackHeaders['x-request-id'])addHeaderDict
addHeaderDict adds several headers to every request that this taxonomy object sends.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: Taxonomy. The same taxonomy, for chaining.
Validation
- There is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeaderDict sends no request.
- Copies every key of headerDict into the headers of this object. A key that the object already holds gets the new value.
- The first header change on this object copies the header map that it shares with the stack. The change then applies to this object only.
Example
Basic usage: send two extra headers from one taxonomy object
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const taxonomy = stack.taxonomy('<TAXONOMY_UID>')
.addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'docs-456' })
// Every request this object sends from now on carries both headers
console.log(taxonomy.stackHeaders)create
create creates a taxonomy in the stack from the details you pass.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Request body with the details under taxonomy. |
| data.taxonomy.uid (required) | string | Unique ID of the taxonomy in the stack. |
| data.taxonomy.name (required) | string | Display name of the taxonomy. |
| data.taxonomy.description | string | Description of the taxonomy. |
| param | object | Query parameters, sent as given. |
Returns: Promise<Taxonomy>. The new taxonomy.
Validation
- There is no client-side validation. create sends data as the JSON body as it is.
- create exists only on taxonomy(). On taxonomy('<TAXONOMY_UID>') it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/taxonomies with data as the body, as Create a taxonomy describes.
- The API reference points to the restricted keywords for UIDs. Avoid reserved words in data.taxonomy.uid.
- Resolves to a new Taxonomy object in the single-taxonomy form, with fetch, update and terms, for example.
Example
Basic usage: create a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const taxonomy = await stack.taxonomy().create({
taxonomy: { uid: 'docs_test_vehicles', name: 'docs-test-vehicles' }
})
console.log(taxonomy.uid, taxonomy.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: create a taxonomy with a description on a branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const taxonomy = await stack.taxonomy().create(
{
taxonomy: {
uid: 'docs_test_vehicles',
name: 'docs-test-vehicles',
description: 'Vehicle types for product pages'
}
},
{} // query parameters, sent as given
)
console.log(taxonomy.uid, taxonomy.description)
} catch (error) {
console.error(error.errorMessage)
}delete
delete removes the taxonomy whose UID you passed to taxonomy('<TAXONOMY_UID>'), with all its terms.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.force (required) | boolean | Set to true to confirm the deletion. |
Returns: Promise<Response>. The status and status text of the API response.
Warning A successful delete removes the taxonomy and every term in it. The API also removes the terms from the content types and entries that use them, and from the delivery data of published entries in all environments. The SDK has no method that restores a deleted taxonomy.
Validation
- There is no client-side validation. The SDK does not check param.force.
- delete exists only on taxonomy('<TAXONOMY_UID>') and on the objects that create, fetch and query().find() return. On taxonomy() it is undefined, and calling it throws TypeError.
- The API reference lists force=true as required to confirm the deletion. Pass { force: true }.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends DELETE /v3/taxonomies/{taxonomy_uid} with every key of param as a query parameter, as Delete a taxonomy describes.
- The API answers with 204 and an empty body, so delete resolves to { status, statusText }. When the API answers with a body, delete resolves to that body instead.
Example
Basic usage: delete a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.taxonomy('<TAXONOMY_UID>').delete({ force: true })
console.log(response.status)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}export
export retrieves the taxonomy whose UID you passed to taxonomy('<TAXONOMY_UID>') with all its terms, as JSON or CSV. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters, sent as given. |
| params.format | string | File format, json or csv. |
| params.locale | string | Locale to export the taxonomy in. |
Returns: Promise<Response>. The exported taxonomy and its terms.
Validation
- There is no client-side validation.
- export exists only on taxonomy('<TAXONOMY_UID>') and on the objects that create, fetch and query().find() return. On taxonomy() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/taxonomies/{taxonomy_uid}/export with every key of params as a query parameter, as Export a taxonomy describes.
- Resolves to the response body. axios parses a JSON export into an object and returns a CSV export as a string.
- export writes no file. Save the result yourself, as the CSV example below does.
Example
Basic usage: export a taxonomy as JSON
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const exported = await stack.taxonomy('<TAXONOMY_UID>').export()
console.log(JSON.stringify(exported, null, 2))
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: save the French version of a taxonomy as a CSV file
import { writeFile } from 'node:fs/promises'
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const csv = await stack.taxonomy('<TAXONOMY_UID>').export({ format: 'csv', locale: 'fr-fr' })
await writeFile('<FILE_PATH>', csv)
console.log('Saved the taxonomy to <FILE_PATH>')
} catch (error) {
console.error(error.errorMessage)
}fetch
fetch retrieves the taxonomy whose UID you passed to taxonomy('<TAXONOMY_UID>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.locale | string | Locale to read the taxonomy in. |
| param.include_fallback | boolean | Follows the locale fallback chain for a missing version. |
| param.include_terms_count | boolean | Adds the term count of the taxonomy. |
| param.include_referenced_terms_count | boolean | Adds the count of terms that entries use. |
| param.include_referenced_entries_count | boolean | Adds the count of entries that use terms. |
Returns: Promise<Taxonomy>. The requested taxonomy.
Validation
- There is no client-side validation.
- fetch exists only on taxonomy('<TAXONOMY_UID>') and on the objects that create, update and query().find() return. On taxonomy() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/taxonomies/{taxonomy_uid} with every key of param as a query parameter, as Get a single taxonomy describes.
- Resolves to a new Taxonomy object that holds the taxonomy fields. The object you called fetch on does not change.
Example
Basic usage: read one taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const taxonomy = await stack.taxonomy('<TAXONOMY_UID>').fetch()
console.log(taxonomy.uid, taxonomy.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: read the French version of a taxonomy with its counts
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const taxonomy = await stack.taxonomy('<TAXONOMY_UID>').fetch({
locale: 'fr-fr',
include_fallback: true,
include_terms_count: true,
include_referenced_terms_count: true,
include_referenced_entries_count: true
})
console.log(taxonomy.name, taxonomy.terms_count, taxonomy.referenced_entries_count)
} catch (error) {
console.error(error.errorMessage)
}import
import creates a taxonomy and its terms from a JSON or CSV file.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Holds the file path. |
| data.taxonomy (required) | string | Path of the JSON or CSV file to import. |
| params | object | Query parameters, sent as given. |
| params.locale | string | Locale to import the taxonomy in. |
Returns: Promise<Taxonomy>. The imported taxonomy.
Validation
- There is no client-side validation. The SDK does not check that the file exists before it sends the request.
- import exists only on taxonomy(). On taxonomy('<TAXONOMY_UID>') it is undefined, and calling it throws TypeError.
- Without data, the returned promise rejects with an Error, because the SDK reads data.taxonomy before it sends anything.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/taxonomies/import with the file as multipart/form-data in a field named taxonomy, as Import a taxonomy describes.
- The API returns a terms_count field with the number of imported terms, not the terms themselves. Call terms on the result to read them.
- Reads the file with the Node.js fs module, so import runs only in Node.js.
- Resolves to a new Taxonomy object in the single-taxonomy form.
Example
Basic usage: import a taxonomy from a JSON file
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const taxonomy = await stack.taxonomy().import({ taxonomy: '<FILE_PATH>' })
console.log(taxonomy.uid, taxonomy.terms_count)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: import a taxonomy in French
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const taxonomy = await stack.taxonomy().import({ taxonomy: '<FILE_PATH>' }, { locale: 'fr-fr' })
console.log(taxonomy.uid, taxonomy.terms_count)
} catch (error) {
console.error(error.errorMessage)
}locales
locales lists the language versions of the taxonomy whose UID you passed to taxonomy('<TAXONOMY_UID>').
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters, sent as given. |
Returns: Promise<Response>. The API response with the language versions of the taxonomy.
Validation
- There is no client-side validation.
- locales exists only on taxonomy('<TAXONOMY_UID>') and on the objects that create, fetch and query().find() return. On taxonomy() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/taxonomies/{taxonomy_uid}/locales with every key of params as a query parameter.
- Resolves to the response body as the API returns it. The SDK describes it as a taxonomies array with one item per locale, each with locale and localized.
Example
Basic usage: list the language versions of a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.taxonomy('<TAXONOMY_UID>').locales()
for (const version of response.taxonomies) {
console.log(version.locale, version.name, version.localized)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: list the language versions on a branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const response = await stack.taxonomy('<TAXONOMY_UID>').locales({})
console.log(response.taxonomies.length)
} catch (error) {
console.error(error.errorMessage)
}localize
localize adds a language version of the taxonomy whose UID you passed to taxonomy('<TAXONOMY_UID>'), with translated values.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Request body with the translated values under taxonomy. |
| data.taxonomy.uid | string | UID of the taxonomy. |
| data.taxonomy.name (required) | string | Translated name of the taxonomy. |
| data.taxonomy.description | string | Translated description of the taxonomy. |
| params | object | Query parameters, sent as given. |
| params.locale (required) | string | Locale code of the new language version. |
Returns: Promise<Taxonomy>. The localized taxonomy.
Validation
- There is no client-side validation. The SDK does not check data or params.locale.
- localize exists only on taxonomy('<TAXONOMY_UID>') and on the objects that create, fetch and query().find() return. On taxonomy() it is undefined, and calling it throws TypeError.
- The API reference lists the locale query parameter as required. Pass it in params.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/taxonomies/{taxonomy_uid} with data as the body and every key of params as a query parameter, as Localize a taxonomy describes.
- Resolves to a new Taxonomy object that holds the localized fields.
- To change an existing language version, call update with locale instead.
Example
Basic usage: add a French version of a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const localized = await stack.taxonomy('<TAXONOMY_UID>').localize(
{ taxonomy: { name: 'Types de véhicules' } },
{ locale: 'fr-fr' }
)
console.log(localized.uid, localized.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: add a French version with a description
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const localized = await stack.taxonomy('<TAXONOMY_UID>').localize(
{
taxonomy: {
uid: '<TAXONOMY_UID>',
name: 'Types de véhicules',
description: 'Types de véhicules pour les pages produit'
}
},
{ locale: 'fr-fr' }
)
console.log(localized.name, localized.description)
} catch (error) {
console.error(error.errorMessage)
}publish
publish starts a job that publishes one or more taxonomies, with all their terms, to the environments and locales you name. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Request body with the publish details. |
| data.locales (required) | string[] | Locale codes to publish to. |
| data.environments (required) | string[] | Environment names to publish to. |
| data.items (required) | object[] | Taxonomies to publish. |
| data.items[].uid (required) | string | UID of one taxonomy. |
| api_version | string | Value of the api_version header. |
| params | object | Query parameters, sent as given, except branch. |
| params.branch | string | Branch whose locale fallback the job uses. |
Returns: Promise<Response>. The API response with a notice and the job ID.
Validation
- There is no client-side validation. publish sends data as the JSON body as it is.
- publish exists only on taxonomy(). On taxonomy('<TAXONOMY_UID>') it is undefined, and calling it throws TypeError.
- The API reference lists the api_version header as required. Pass api_version, because the SDK sends the header only when the value is a non-empty string.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/taxonomies/publish with data as the body, as Publish a taxonomy describes.
- The API publishes each taxonomy as a whole, with every term it contains. The API reference states that the API does not publish individual terms.
- params.branch becomes the branch header of this request and replaces the branch of the stack. The SDK sends every other key of params as a query parameter.
- The API starts a job and returns its ID. Track the outcome of the job in the publish queue of the stack.
- Resolves to the response body as the API returns it. The TypeScript declarations of the SDK describe it as { notice, job_id }.
Note The API reference describes taxonomy publishing as a plan-based feature that your organization might not have by default.
Example
Basic usage: publish a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.taxonomy().publish(
{
locales: ['<LOCALE>'],
environments: ['<ENVIRONMENT>'],
items: [{ uid: '<TAXONOMY_UID>' }]
},
'3.2'
)
console.log(response.notice, response.job_id)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: publish a taxonomy with the locale fallback of a branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.taxonomy().publish(
{
locales: ['<LOCALE>', 'fr-fr'],
environments: ['<ENVIRONMENT>'],
items: [{ uid: '<TAXONOMY_UID>' }]
},
'3.2',
{ branch: '<BRANCH>' }
)
console.log(response.notice, response.job_id)
} catch (error) {
console.error(error.errorMessage)
}query
query builds a request for the taxonomies of the stack. It sends nothing until you call a method of the returned query.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the request. |
| params.query | object | Condition on taxonomy fields, sent as JSON. |
| params.locale | string | Locale to read the taxonomies in. |
| params.include_fallback | boolean | Follows the locale fallback chain for missing versions. |
| params.include_terms_count | boolean | Adds the term count of each taxonomy. |
| params.include_referenced_terms_count | boolean | Adds the count of terms that entries use. |
| params.include_referenced_entries_count | boolean | Adds the count of entries that use terms. |
| params.include_count | boolean | Adds the total number of taxonomies. |
| params.deleted | boolean | Returns only deleted taxonomies. |
| params.typeahead | string | Returns taxonomies that match this text. |
| params.asc | string | Field to sort by in ascending order. |
| params.desc | string | Field to sort by in descending order. |
| params.limit | number | Maximum number of taxonomies to return. |
| params.skip | number | Number of taxonomies to skip. |
Returns: Query. A query for taxonomies, sent when you call find(), findOne() or count().
Validation
- There is no client-side validation.
- query exists only on taxonomy(). On taxonomy('<TAXONOMY_UID>') it is undefined, and calling it throws TypeError.
- An invalid value surfaces as a rejected promise from the request method you call next.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. query copies the headers of this object and params, and returns a Query object.
- find and findOne send GET /v3/taxonomies and resolve to Taxonomy objects in items, as Get all taxonomies describes. count resolves to the response body.
- Each Taxonomy in items is the single-taxonomy form, with fetch, update and terms, for example.
- The SDK sends params.query as query=<JSON>, and every other key of params as a query parameter.
Example
Basic usage: list the taxonomies of a stack
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const result = await stack.taxonomy().query().find()
for (const taxonomy of result.items) {
console.log(taxonomy.uid, taxonomy.name)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: read the second page of French taxonomies with counts
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const result = await stack.taxonomy()
.query({
query: { uid: '<TAXONOMY_UID>' },
locale: 'fr-fr',
include_fallback: true,
include_terms_count: true,
include_referenced_terms_count: true,
include_referenced_entries_count: true,
include_count: true,
deleted: false,
typeahead: 'vehic',
asc: 'name',
limit: 10,
skip: 10
})
.find()
console.log(result.count)
for (const taxonomy of result.items) {
console.log(taxonomy.uid, taxonomy.terms_count)
}
} catch (error) {
console.error(error.errorMessage)
}Sort in descending order: list the newest taxonomies first
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const result = await stack.taxonomy().query({ desc: 'created_at', limit: 5 }).find()
for (const taxonomy of result.items) {
console.log(taxonomy.uid, taxonomy.created_at)
}
} catch (error) {
console.error(error.errorMessage)
}removeHeader
removeHeader removes one header from the requests that this taxonomy object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: Taxonomy. The same taxonomy, for chaining.
Validation
- There is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. removeHeader sends no request.
- Removing a header that the object shares with the stack first copies the shared headers, so the stack and other objects keep the header.
- The SDK adds some headers at request time, for example the authorization header of the client. removeHeader cannot remove those.
Example
Basic usage: send requests from one taxonomy object without the branch header
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
const taxonomy = stack.taxonomy('<TAXONOMY_UID>').removeHeader('branch')
// This object now works with the default branch
console.log(taxonomy.stackHeaders.branch)terms
terms creates a Terms object for one term of this taxonomy, or for all its terms. The following table lists its parameters:
| Name | Type | Description |
|---|---|---|
| uid | string | UID of the term to open. |
Returns: Terms. A new terms object.
Validation
- There is no client-side validation. An empty string returns the collection form, which is also the default.
- terms exists only on taxonomy('<TAXONOMY_UID>') and on the objects that create, fetch and query().find() return. On taxonomy() it is undefined, and calling it throws TypeError.
- An invalid value surfaces as a rejected promise from the request method you call next.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. terms sends no request.
- With a UID, the object has fetch, update and move, for example. Without one, it has create and query. The Terms page lists every method of each form.
- The new object takes the taxonomy UID of this object and shares its headers until either object changes its own.
Example
Basic usage: read one term of a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const term = await stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>').fetch()
console.log(term.uid, term.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Collection form: list the terms of a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const result = await stack.taxonomy('<TAXONOMY_UID>').terms().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}unpublish
unpublish starts a job that unpublishes one or more taxonomies, with all their terms, from the environments and locales you name. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Request body with the unpublish details. |
| data.locales (required) | string[] | Locale codes to unpublish from. |
| data.environments (required) | string[] | Environment names to unpublish from. |
| data.items (required) | object[] | Taxonomies to unpublish. |
| data.items[].uid (required) | string | UID of one taxonomy. |
| api_version | string | Value of the api_version header. |
| params | object | Query parameters, sent as given, except branch. |
| params.branch | string | Branch whose locale fallback the job uses. |
Returns: Promise<Response>. The API response with a notice and the job ID.
Warning The job removes each taxonomy and all its terms from the environments and locales you name, so the taxonomy no longer resolves on the Content Delivery API there. Call publish again to restore it.
Validation
- There is no client-side validation. unpublish sends data as the JSON body as it is.
- unpublish exists only on taxonomy(). On taxonomy('<TAXONOMY_UID>') it is undefined, and calling it throws TypeError.
- The API reference lists the api_version header as required. Pass api_version, because the SDK sends the header only when the value is a non-empty string.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/taxonomies/unpublish with data as the body, as Unpublish a taxonomy describes.
- The API unpublishes each taxonomy as a whole, with every term it contains. The API reference states that the API does not unpublish individual terms.
- params.branch becomes the branch header of this request and replaces the branch of the stack. The SDK sends every other key of params as a query parameter.
- The API starts a job and returns its ID. Track the outcome of the job in the publish queue of the stack.
- Resolves to the response body as the API returns it. The TypeScript declarations of the SDK describe it as { notice, job_id }.
Note The API reference describes taxonomy publishing as a plan-based feature that your organization might not have by default.
Example
Basic usage: unpublish a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.taxonomy().unpublish(
{
locales: ['<LOCALE>'],
environments: ['<ENVIRONMENT>'],
items: [{ uid: '<TAXONOMY_UID>' }]
},
'3.2'
)
console.log(response.notice, response.job_id)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: unpublish a taxonomy with the locale fallback of a branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.taxonomy().unpublish(
{
locales: ['<LOCALE>', 'fr-fr'],
environments: ['<ENVIRONMENT>'],
items: [{ uid: '<TAXONOMY_UID>' }]
},
'3.2',
{ branch: '<BRANCH>' }
)
console.log(response.notice, response.job_id)
} catch (error) {
console.error(error.errorMessage)
}update
update saves the fields that this taxonomy object holds to the stack.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.locale | string | Locale to save the taxonomy in. |
Returns: Promise<Taxonomy>. The updated taxonomy.
Validation
- There is no client-side validation.
- update exists only on taxonomy('<TAXONOMY_UID>') and on the objects that create, fetch and query().find() return. On taxonomy() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends PUT /v3/taxonomies/{taxonomy_uid} with the body { taxonomy: <fields of this object> }, as Update a taxonomy describes. The SDK leaves out uid, created_at, created_by, updated_at, updated_by and its own keys.
- The body holds only the fields this object has. Call fetch first, change the fields of the object it returns, and then call update.
- Resolves to a new Taxonomy object with the saved fields.
Example
Basic usage: rename a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const taxonomy = await stack.taxonomy('<TAXONOMY_UID>').fetch()
taxonomy.name = 'Vehicle types'
taxonomy.description = 'Vehicle types for product pages'
const updated = await taxonomy.update()
console.log(updated.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: update the French version of a taxonomy
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const taxonomy = await stack.taxonomy('<TAXONOMY_UID>').fetch({ locale: 'fr-fr' })
taxonomy.name = 'Types de véhicules'
const updated = await taxonomy.update({ locale: 'fr-fr' })
console.log(updated.name)
} catch (error) {
console.error(error.errorMessage)
}