Taxonomy

View as Markdown

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.

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

CapabilitySupportedNotes / Alternative
Unlocalize a taxonomyNoThe SDK has no method for Unlocalize a taxonomy
Publish single termsNoThe API publishes a taxonomy together with all its terms
Import from a file in a browserNoimport reads a file path with the Node.js fs module

Method Index

Work with the taxonomies of a stack. Available on stack.taxonomy().

Method NameReturnsDescription
queryA query for taxonomies, sent when you call find(), findOne() or count().Builds a taxonomy query.
createThe new taxonomy.Creates a taxonomy.
importThe imported taxonomy.Imports a taxonomy from a JSON or CSV file.

Publish taxonomies. Available on stack.taxonomy().

Method NameReturnsDescription
publishThe API response with a notice and the job ID.Publishes taxonomies to environments and locales.
unpublishThe 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 NameReturnsDescription
fetchThe requested taxonomy.Retrieves one taxonomy.
updateThe updated taxonomy.Saves the fields of this object.
deleteThe status and status text of the API response.Deletes the taxonomy and its terms.
exportThe exported taxonomy and its terms.Exports the taxonomy as JSON or CSV.
localesThe API response with the language versions of the taxonomy.Lists the language versions of the taxonomy.
localizeThe localized taxonomy.Adds a language version of the taxonomy.
termsA new terms object.Opens the terms of the taxonomy.

Set request headers. Available on both forms.

Method NameReturnsDescription
addHeaderThe same taxonomy, for chaining.Adds one request header.
addHeaderDictThe same taxonomy, for chaining.Adds several request headers.
removeHeaderThe 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.

NameTypeDescription
key (required)string

Header name, for example x-request-id.

Default: Not applicable
value (required)string

Header value to send.

Default: Not applicable

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.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

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.

NameTypeDescription
data (required)object

Request body with the details under taxonomy.

Default: Not applicable
data.taxonomy.uid (required)string

Unique ID of the taxonomy in the stack.

Default: Not applicable
data.taxonomy.name (required)string

Display name of the taxonomy.

Default: Not applicable
data.taxonomy.descriptionstring

Description of the taxonomy.

Default: API default
paramobject

Query parameters, sent as given.

Default: undefined (sends no query parameters)

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.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.force (required)boolean

Set to true to confirm the deletion.

Default: Not applicable

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.

NameTypeDescription
paramsobject

Query parameters, sent as given.

Default: {}
params.formatstring

File format, json or csv.

Default: API default (JSON)
params.localestring

Locale to export the taxonomy in.

Default: API default (master locale)

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>').

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.localestring

Locale to read the taxonomy in.

Default: API default (master locale)
param.include_fallbackboolean

Follows the locale fallback chain for a missing version.

Default: API default
param.include_terms_countboolean

Adds the term count of the taxonomy.

Default: API default
param.include_referenced_terms_countboolean

Adds the count of terms that entries use.

Default: API default
param.include_referenced_entries_countboolean

Adds the count of entries that use terms.

Default: API default

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.

NameTypeDescription
data (required)object

Holds the file path.

Default: Not applicable
data.taxonomy (required)string

Path of the JSON or CSV file to import.

Default: Not applicable
paramsobject

Query parameters, sent as given.

Default: {}
params.localestring

Locale to import the taxonomy in.

Default: API default (master locale)

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>').

NameTypeDescription
paramsobject

Query parameters, sent as given.

Default: {}

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.

NameTypeDescription
data (required)object

Request body with the translated values under taxonomy.

Default: Not applicable
data.taxonomy.uidstring

UID of the taxonomy.

Default: API default
data.taxonomy.name (required)string

Translated name of the taxonomy.

Default: Not applicable
data.taxonomy.descriptionstring

Translated description of the taxonomy.

Default: API default
paramsobject

Query parameters, sent as given.

Default: {}
params.locale (required)string

Locale code of the new language version.

Default: Not applicable

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.

NameTypeDescription
data (required)object

Request body with the publish details.

Default: Not applicable
data.locales (required)string[]

Locale codes to publish to.

Default: Not applicable
data.environments (required)string[]

Environment names to publish to.

Default: Not applicable
data.items (required)object[]

Taxonomies to publish.

Default: Not applicable
data.items[].uid (required)string

UID of one taxonomy.

Default: Not applicable
api_versionstring

Value of the api_version header.

Default: '' (header not sent)
paramsobject

Query parameters, sent as given, except branch.

Default: {}
params.branchstring

Branch whose locale fallback the job uses.

Default: undefined (stack branch header applies)

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.

NameTypeDescription
paramsobject

Query parameters for the request.

Default: {}
params.queryobject

Condition on taxonomy fields, sent as JSON.

Default: API default
params.localestring

Locale to read the taxonomies in.

Default: API default (master locale)
params.include_fallbackboolean

Follows the locale fallback chain for missing versions.

Default: API default
params.include_terms_countboolean

Adds the term count of each taxonomy.

Default: API default
params.include_referenced_terms_countboolean

Adds the count of terms that entries use.

Default: API default
params.include_referenced_entries_countboolean

Adds the count of entries that use terms.

Default: API default
params.include_countboolean

Adds the total number of taxonomies.

Default: API default
params.deletedboolean

Returns only deleted taxonomies.

Default: API default
params.typeaheadstring

Returns taxonomies that match this text.

Default: API default
params.ascstring

Field to sort by in ascending order.

Default: API default
params.descstring

Field to sort by in descending order.

Default: API default
params.limitnumber

Maximum number of taxonomies to return.

Default: API default
params.skipnumber

Number of taxonomies to skip.

Default: API default

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.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

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:

NameTypeDescription
uidstring

UID of the term to open.

Default: '' (returns the collection form)

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.

NameTypeDescription
data (required)object

Request body with the unpublish details.

Default: Not applicable
data.locales (required)string[]

Locale codes to unpublish from.

Default: Not applicable
data.environments (required)string[]

Environment names to unpublish from.

Default: Not applicable
data.items (required)object[]

Taxonomies to unpublish.

Default: Not applicable
data.items[].uid (required)string

UID of one taxonomy.

Default: Not applicable
api_versionstring

Value of the api_version header.

Default: '' (header not sent)
paramsobject

Query parameters, sent as given, except branch.

Default: {}
params.branchstring

Branch whose locale fallback the job uses.

Default: undefined (stack branch header applies)

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.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.localestring

Locale to save the taxonomy in.

Default: API default (master locale)

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)
}