Terms

View as Markdown

Terms

A term is one item in the hierarchy of a taxonomy, for example cars under vehicles. The Terms class manages the terms of one taxonomy through the Content Management API (CMA). Use this class to

  • list and create the terms of a taxonomy
  • read, update, localize, move and delete one term
  • read the ancestors and descendants of a term
  • search terms across all the taxonomies of the stack

Call the terms method of a Taxonomy object that has a UID to get an object, for example stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>'). The method name is plural, terms, for one term and for all terms.

Instance State

  • Call terms() without a UID to work with all the terms of the taxonomy, for example create and query.
  • Call terms('<TERM_UID>') to work with one term, for example fetch and move.
  • Each form has only its own methods, except search and the three header methods, which both forms have. fetch is undefined on terms(), and create is undefined on terms('<TERM_UID>'), so calling the wrong one throws TypeError.
  • terms exists only on taxonomy('<TAXONOMY_UID>'). On taxonomy() it is undefined.
  • The objects that create, fetch, update, move, localize and query().find() return are the single-term form.

Warning terms('') 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 terms of a taxonomy describes.

Headers.

  • Every request sends the headers of this object, which start as the headers of the taxonomy object. Change them for this object only with addHeader, addHeaderDict and removeHeader.

Errors from ancestors, descendants and search.

  • These three methods reject with the axios error itself, not with the error object of the other methods. Read error.status and error.response.data.error_message.
  • They also print the error to the console with console.error before they reject.

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 termNoThe SDK has no method for Unlocalize a term
Search the terms of one taxonomy onlyNosearch searches every taxonomy. Use query with typeahead for one taxonomy
Page or filter ancestors and descendantsNoKnown issue on the ancestors page

Method Index

Work with the terms of a taxonomy. Available on stack.taxonomy('<TAXONOMY_UID>').terms(). The search method is in the last group.

Method NameReturnsDescription
queryA query for terms, sent when you call find(), findOne() or count().Builds a term query.
createThe new term.Creates a term.

Read and change one term. Available on stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>').

Method NameReturnsDescription
fetchThe requested term.Retrieves one term.
updateThe updated term.Saves the fields of this object.
deleteThe status and status text of the API response.Deletes the term and its child terms.
moveThe moved term.Moves or reorders the term.
localesThe API response with the language versions of the term.Lists the language versions of the term.
localizeThe localized term.Adds a language version of the term.

Read the hierarchy of one term. Available on stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>').

Method NameReturnsDescription
ancestorsThe API response with the ancestor terms.Lists the terms above the term.
descendantsThe API response with the descendant terms.Lists the terms below the term.

Search and set request headers. Available on both forms.

Method NameReturnsDescription
searchThe API response with the matching terms.Searches terms across all taxonomies.
addHeaderThe same terms object, for chaining.Adds one request header.
addHeaderDictThe same terms object, for chaining.Adds several request headers.
removeHeaderThe same terms object, for chaining.Removes one request header.

Class-Level Snippet

The snippet below creates a parent term and a child term, and then lists the ancestors of the child.

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

try {
  const parent = await taxonomy.terms().create({
    term: { uid: 'docs_test_vehicles', name: 'docs-test-vehicles', parent_uid: null, order: 1 }
  })
  const child = await taxonomy.terms().create({
    term: { uid: 'docs_test_cars', name: 'docs-test-cars', parent_uid: parent.uid, order: 1 }
  })
  console.log(child.uid, child.parent_uid)

  const response = await taxonomy.terms(child.uid).ancestors()
  console.log(response)
} catch (error) {
  // The API rejected the request. ancestors rejects with the axios error, the other methods with the SDK error.
  console.error(error.status, error.errorMessage || error.response?.data?.error_message)
}

Methods

Each method of the Terms class has its own section below, with its parameters, validation rules, behavior, and examples.

addHeader

addHeader adds one header to every request that this terms 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: Terms. The same terms object, 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.
  • query copies the headers of this object into the query it returns. Change the headers first, then call it.

Example

Basic usage: tag the requests of one terms object

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const terms = stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>').addHeader('x-request-id', 'docs-123')
// Every request this object sends from now on carries the header
console.log(terms.stackHeaders['x-request-id'])

addHeaderDict

addHeaderDict adds several headers to every request that this terms object sends.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: Terms. The same terms object, 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 terms object

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const terms = stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_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(terms.stackHeaders)

ancestors

ancestors lists the terms above the term whose UID you passed to terms('<TERM_UID>') in the hierarchy of the taxonomy.

NameTypeDescription
paramsobject

Extra request headers for this call.

Default: {}

Returns: Promise<Response>. The API response with the ancestor terms.

Known issue ancestors sends the keys of params as request headers, not as query parameters, so options that the API reference lists as query parameters, such as locale, limit and skip, do not reach the API as query parameters. Call ancestors() without them and page or filter the result in your code.

Validation

  • There is no client-side validation.
  • ancestors exists only on terms('<TERM_UID>') and on the objects that create, fetch and query().find() return. On terms() it is undefined, and calling it throws TypeError.
  • When the API rejects the request, the returned promise rejects with the axios error. Read error.status and error.response.data.error_message. ancestors also prints the error to the console before it rejects.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/ancestors, as Get ancestors of a term describes.
  • Resolves to the response body as the API returns it, plus a stackHeaders key that the SDK adds with the headers of this object.

Example

Basic usage: list the ancestor terms of a term

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>').terms('<TERM_UID>').ancestors()
  console.log(response)
} catch (error) {
  // ancestors rejects with the axios error. The API error body is in error.response.data.
  console.error(error.status, error.response?.data?.error_message)
}

All parameters: send one request header with the call

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // Each key of params becomes a request header of this call
  const response = await stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>').ancestors({ 'x-request-id': 'docs-123' })
  console.log(response)
} catch (error) {
  console.error(error.status, error.response?.data?.error_message)
}

create

create creates a term in the taxonomy from the details you pass.

NameTypeDescription
data (required)object

Request body with the details under term.

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

Unique ID of the term.

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

Display name of the term.

Default: Not applicable
data.term.parent_uidstring

UID of the parent term. null creates a root term.

Default: API default
data.term.order (required)number

Position of the term among its siblings, from 1.

Default: Not applicable
paramobject

Query parameters, sent as given.

Default: undefined (sends no query parameters)
param.include_children_countboolean

Adds the child term count to the response.

Default: API default
param.include_referenced_entries_countboolean

Adds the count of entries that use the term.

Default: API default

Returns: Promise<Terms>. The new term.

Validation

  • There is no client-side validation. create sends data as the JSON body as it is.
  • create exists only on terms(). On terms('<TERM_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/{taxonomy_uid}/terms with data as the body and every key of param as a query parameter, as Create a term describes.
  • The API reference asks you to set the order of each new term. For a root term, set parent_uid to null. For a child term, set parent_uid to the UID of its parent.
  • Resolves to a new Terms object in the single-term form, with the taxonomy UID of this object.

Example

Basic usage: create a root term

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().create({
    term: { uid: 'docs_test_vehicles', name: 'docs-test-vehicles', parent_uid: null, order: 1 }
  })
  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)
}

All parameters: create a child term and read its counts

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().create(
    { term: { uid: 'docs_test_cars', name: 'docs-test-cars', parent_uid: '<TERM_UID>', order: 2 } },
    { include_children_count: true, include_referenced_entries_count: true }
  )
  console.log(term.uid, term.parent_uid, term.children_count)
} catch (error) {
  console.error(error.errorMessage)
}

delete

delete removes the term whose UID you passed to terms('<TERM_UID>'), with all its child 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 term and every child term under it. The API also removes them from the entries that use them, and from the delivery data of published entries in all environments. The SDK has no method that restores a deleted term.

Validation

  • There is no client-side validation. The SDK does not check param.force.
  • delete exists only on terms('<TERM_UID>') and on the objects that create, fetch and query().find() return. On terms() 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}/terms/{term_uid} with every key of param as a query parameter, as Delete a term 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 term

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>').terms('<TERM_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)
}

descendants

descendants lists the terms below the term whose UID you passed to terms('<TERM_UID>') in the hierarchy of the taxonomy.

NameTypeDescription
paramsobject

Extra request headers for this call.

Default: {}

Returns: Promise<Response>. The API response with the descendant terms.

Known issue descendants sends the keys of params as request headers, not as query parameters, so options that the API reference lists as query parameters, such as locale, limit and skip, do not reach the API as query parameters. Call descendants() without them and page or filter the result in your code.

Validation

  • There is no client-side validation.
  • descendants exists only on terms('<TERM_UID>') and on the objects that create, fetch and query().find() return. On terms() it is undefined, and calling it throws TypeError.
  • When the API rejects the request, the returned promise rejects with the axios error. Read error.status and error.response.data.error_message. descendants also prints the error to the console before it rejects.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/taxonomies/{taxonomy_uid}/terms/{term_uid}/descendants, as Get descendants of a term describes.
  • Resolves to the response body as the API returns it, plus a stackHeaders key that the SDK adds with the headers of this object.

Example

Basic usage: list the descendant terms of a term

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>').terms('<TERM_UID>').descendants()
  console.log(response)
} catch (error) {
  // descendants rejects with the axios error. The API error body is in error.response.data.
  console.error(error.status, error.response?.data?.error_message)
}

All parameters: send one request header with the call

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // Each key of params becomes a request header of this call
  const response = await stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>').descendants({ 'x-request-id': 'docs-123' })
  console.log(response)
} catch (error) {
  console.error(error.status, error.response?.data?.error_message)
}

fetch

fetch retrieves the term whose UID you passed to terms('<TERM_UID>').

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.localestring

Locale to read the term in.

Default: API default (master locale)
param.include_fallbackboolean

Follows the locale fallback chain for a missing version.

Default: API default
param.include_children_countboolean

Adds the child term count.

Default: API default
param.include_referenced_entries_countboolean

Adds the count of entries that use the term.

Default: API default

Returns: Promise<Terms>. The requested term.

Validation

  • There is no client-side validation.
  • fetch exists only on terms('<TERM_UID>') and on the objects that create, update and query().find() return. On terms() 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}/terms/{term_uid} with every key of param as a query parameter, as Get a single term describes.
  • Resolves to a new Terms object that holds the term fields. The object you called fetch on does not change.

Example

Basic usage: read one term

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, term.parent_uid)
} 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 term 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 term = await stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>').fetch({
    locale: 'fr-fr',
    include_fallback: true,
    include_children_count: true,
    include_referenced_entries_count: true
  })
  console.log(term.name, term.children_count, term.referenced_entries_count)
} catch (error) {
  console.error(error.errorMessage)
}

locales

locales lists the language versions of the term whose UID you passed to terms('<TERM_UID>'). The following table lists its parameters.

NameTypeDescription
paramsobject

Query parameters, sent as given.

Default: {}

Returns: Promise<Response>. The API response with the language versions of the term.

Validation

  • There is no client-side validation.
  • locales exists only on terms('<TERM_UID>') and on the objects that create, fetch and query().find() return. On terms() 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}/terms/{term_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 terms array with one item per locale.

Example

Basic usage: list the language versions of a term

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>').terms('<TERM_UID>').locales()
  for (const version of response.terms) {
    console.log(version.locale, version.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: 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>').terms('<TERM_UID>').locales({})
  console.log(response.terms.length)
} catch (error) {
  console.error(error.errorMessage)
}

localize

localize adds a language version of the term whose UID you passed to terms('<TERM_UID>'), with translated values.

NameTypeDescription
data (required)object

Request body with the translated values under term.

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

Translated name of the term.

Default: Not applicable
paramsobject

Query parameters, sent as given.

Default: {}
params.locale (required)string

Locale code of the new language version.

Default: Not applicable

Returns: Promise<Terms>. The localized term.

Validation

  • There is no client-side validation. The SDK does not check data or params.locale.
  • localize exists only on terms('<TERM_UID>') and on the objects that create, fetch and query().find() return. On terms() 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}/terms/{term_uid} with data as the body and every key of params as a query parameter, as Localize a term describes.
  • Resolves to a new Terms object that holds the localized fields. It takes its taxonomy UID from the taxonomy_uid field of the response.
  • To change an existing language version, call update with locale instead.

Example

Basic usage: add a French version of a term

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>').terms('<TERM_UID>').localize(
    { term: { name: 'Voitures' } },
    { 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)
}

move

move gives the term whose UID you passed to terms('<TERM_UID>') a new parent, a new position among its siblings, or both.

NameTypeDescription
paramobject

Move details, sent as the body and as query parameters.

Default: {}
param.term.parent_uidstring

UID of the new parent term.

Default: API default
param.term.order (required)number

New position among the sibling terms, from 1.

Default: Not applicable
param.forceboolean

Moves a term that has child terms.

Default: API default (false)

Returns: Promise<Terms>. The moved term.

Validation

  • There is no client-side validation.
  • move exists only on terms('<TERM_UID>') and on the objects that create, fetch and query().find() return. On terms() it is undefined, and calling it throws TypeError.
  • Without force: true, the API rejects a move of a term that has child terms, as Move/Reorder a term states.
  • 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}/terms/{term_uid}/move, as Move/Reorder a term describes.
  • Sends param twice: the SDK sends it as the JSON body and also serializes it into the query string. As a result, force: true reaches the API as the force=true query parameter.
  • move reads none of the fields of this object. Pass the new position in param.
  • With force: true, the API moves the term with its child terms, which changes the hierarchy of those children and of the ancestors.
  • Resolves to a new Terms object with the moved term.

Example

Basic usage: move a term to the first position under a parent

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>').move({
    term: { parent_uid: 'vehicles', order: 1 }
  })
  console.log(term.uid, term.parent_uid)
} 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: move a term that has child terms

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>').move({
    term: { parent_uid: 'vehicles', order: 2 },
    force: true
  })
  console.log(term.uid, term.parent_uid)
} catch (error) {
  console.error(error.errorMessage)
}

query

query builds a request for the terms of the taxonomy. It sends nothing until you call a method of the returned query.

NameTypeDescription
paramsobject

Query parameters for the request.

Default: {}
params.queryobject

Condition on term fields, sent as JSON.

Default: API default
params.localestring

Locale to read the terms in.

Default: API default (master locale)
params.include_fallbackboolean

Follows the locale fallback chain for missing versions.

Default: API default
params.depthnumber

Returns terms from the root level down to this depth.

Default: API default
params.include_children_countboolean

Adds the child term count of each term.

Default: API default
params.include_referenced_entries_countboolean

Adds the count of entries that use each term.

Default: API default
params.include_countboolean

Adds the total number of terms.

Default: API default
params.include_orderboolean

Adds the order of each term.

Default: API default
params.typeaheadstring

Returns terms that match this text.

Default: API default
params.deletedboolean

Returns only deleted terms.

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 terms to return.

Default: API default
params.skipnumber

Number of terms to skip.

Default: API default

Returns: Query. A query for terms, sent when you call find(), findOne() or count().

Validation

  • There is no client-side validation.
  • query exists only on terms(). On terms('<TERM_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/{taxonomy_uid}/terms and resolve to Terms objects in items, as Get all terms of a taxonomy describes. count resolves to the response body.
  • Each Terms object in items takes its taxonomy UID from the taxonomy_uid field of the term in the response.
  • The SDK sends params.query as query=<JSON>, and every other key of params as a query parameter.

Example

Basic usage: 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()
  for (const term of result.items) {
    console.log(term.uid, term.name, term.parent_uid)
  }
} 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 two levels of French terms 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('<TAXONOMY_UID>').terms()
    .query({
      query: { uid: '<TERM_UID>' },
      locale: 'fr-fr',
      include_fallback: true,
      depth: 2,
      include_children_count: true,
      include_referenced_entries_count: true,
      include_count: true,
      include_order: true,
      typeahead: 'car',
      deleted: false,
      asc: 'name',
      limit: 10,
      skip: 0
    })
    .find()
  console.log(result.count)
  for (const term of result.items) {
    console.log(term.uid, term.order, term.children_count)
  }
} catch (error) {
  console.error(error.errorMessage)
}

Sort in descending order: list the newest terms 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('<TAXONOMY_UID>').terms().query({ desc: 'created_at', limit: 5 }).find()
  for (const term of result.items) {
    console.log(term.uid, term.created_at)
  }
} catch (error) {
  console.error(error.errorMessage)
}

removeHeader

removeHeader removes one header from the requests that this terms object sends.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: Terms. The same terms object, 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 terms 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 terms = stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>').removeHeader('branch')
// This object now works with the default branch
console.log(terms.stackHeaders.branch)

search finds the terms whose UID or name matches a text, across all the taxonomies of the stack.

NameTypeDescription
termstring

Text to match against term UIDs and names.

Default: ''
paramsobject

Extra request headers for this call.

Default: {}

Returns: Promise<Response>. The API response with the matching terms.

Known issue search sends the keys of params as request headers, not as query parameters, so options that the API reference lists as query parameters, such as locale, limit and skip, do not reach the API as query parameters. Call search with term only and page or filter the result in your code.

Validation

  • There is no client-side validation.
  • search exists on both terms() and terms('<TERM_UID>').
  • When the API rejects the request, the returned promise rejects with the axios error. Read error.status and error.response.data.error_message. search also prints the error to the console before it rejects.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/taxonomies/$all/terms?typeahead=<term>, as Get all terms across all taxonomies describes. $all is the API keyword for every taxonomy.
  • Searches every taxonomy of the stack, not only the taxonomy of this object. To search one taxonomy, use query with typeahead.
  • Places term in the URL as it is, without URL encoding. Encode a value that holds &, # or + with encodeURIComponent before you pass it.
  • Resolves to the response body as the API returns it, plus a stackHeaders key that the SDK adds with the headers of this object.

Example

Basic usage: find terms that match a text

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>').terms().search('car')
  for (const term of response.terms) {
    console.log(term.taxonomy_uid, term.uid, term.name)
  }
} catch (error) {
  // search rejects with the axios error. The API error body is in error.response.data.
  console.error(error.status, error.response?.data?.error_message)
}

All parameters: search for a text with special characters

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // Each key of params becomes a request header of this call
  const response = await stack.taxonomy('<TAXONOMY_UID>').terms()
    .search(encodeURIComponent('cars & bikes'), { 'x-request-id': 'docs-123' })
  console.log(response.terms.length)
} catch (error) {
  console.error(error.status, error.response?.data?.error_message)
}

update

update saves the fields that this term object holds to the taxonomy.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.localestring

Locale to save the term in.

Default: API default (master locale)

Returns: Promise<Terms>. The updated term.

Validation

  • There is no client-side validation.
  • update exists only on terms('<TERM_UID>') and on the objects that create, fetch and query().find() return. On terms() 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}/terms/{term_uid} with the body { term: <fields of this object> }, as Update a term 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.
  • To change the parent or the position of a term, use move.
  • Resolves to a new Terms object with the saved fields.

Example

Basic usage: rename a term

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()
  term.name = 'Electric cars'
  const updated = await term.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 term

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({ locale: 'fr-fr' })
  term.name = 'Voitures électriques'
  const updated = await term.update({ locale: 'fr-fr' })
  console.log(updated.name)
} catch (error) {
  console.error(error.errorMessage)
}