Terms
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
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Unlocalize a term | No | The SDK has no method for Unlocalize a term |
| Search the terms of one taxonomy only | No | search searches every taxonomy. Use query with typeahead for one taxonomy |
| Page or filter ancestors and descendants | No | Known 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 Name | Returns | Description |
|---|---|---|
| query | A query for terms, sent when you call find(), findOne() or count(). | Builds a term query. |
| create | The new term. | Creates a term. |
Read and change one term. Available on stack.taxonomy('<TAXONOMY_UID>').terms('<TERM_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested term. | Retrieves one term. |
| update | The updated term. | Saves the fields of this object. |
| delete | The status and status text of the API response. | Deletes the term and its child terms. |
| move | The moved term. | Moves or reorders the term. |
| locales | The API response with the language versions of the term. | Lists the language versions of the term. |
| localize | The 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 Name | Returns | Description |
|---|---|---|
| ancestors | The API response with the ancestor terms. | Lists the terms above the term. |
| descendants | The API response with the descendant terms. | Lists the terms below the term. |
Search and set request headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| search | The API response with the matching terms. | Searches terms across all taxonomies. |
| addHeader | The same terms object, for chaining. | Adds one request header. |
| addHeaderDict | The same terms object, for chaining. | Adds several request headers. |
| removeHeader | The 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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
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.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Extra request headers for this call. |
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.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Request body with the details under term. |
| data.term.uid (required) | string | Unique ID of the term. |
| data.term.name (required) | string | Display name of the term. |
| data.term.parent_uid | string | UID of the parent term. null creates a root term. |
| data.term.order (required) | number | Position of the term among its siblings, from 1. |
| param | object | Query parameters, sent as given. |
| param.include_children_count | boolean | Adds the child term count to the response. |
| param.include_referenced_entries_count | boolean | Adds the count of entries that use the term. |
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.
| 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 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.
| Name | Type | Description |
|---|---|---|
| params | object | Extra request headers for this call. |
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>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.locale | string | Locale to read the term in. |
| param.include_fallback | boolean | Follows the locale fallback chain for a missing version. |
| param.include_children_count | boolean | Adds the child term count. |
| param.include_referenced_entries_count | boolean | Adds the count of entries that use the term. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters, sent as given. |
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.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Request body with the translated values under term. |
| data.term.name (required) | string | Translated name of the term. |
| params | object | Query parameters, sent as given. |
| params.locale (required) | string | Locale code of the new language version. |
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.
| Name | Type | Description |
|---|---|---|
| param | object | Move details, sent as the body and as query parameters. |
| param.term.parent_uid | string | UID of the new parent term. |
| param.term.order (required) | number | New position among the sibling terms, from 1. |
| param.force | boolean | Moves a term that has child terms. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the request. |
| params.query | object | Condition on term fields, sent as JSON. |
| params.locale | string | Locale to read the terms in. |
| params.include_fallback | boolean | Follows the locale fallback chain for missing versions. |
| params.depth | number | Returns terms from the root level down to this depth. |
| params.include_children_count | boolean | Adds the child term count of each term. |
| params.include_referenced_entries_count | boolean | Adds the count of entries that use each term. |
| params.include_count | boolean | Adds the total number of terms. |
| params.include_order | boolean | Adds the order of each term. |
| params.typeahead | string | Returns terms that match this text. |
| params.deleted | boolean | Returns only deleted terms. |
| 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 terms to return. |
| params.skip | number | Number of terms to skip. |
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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
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
search finds the terms whose UID or name matches a text, across all the taxonomies of the stack.
| Name | Type | Description |
|---|---|---|
| term | string | Text to match against term UIDs and names. |
| params | object | Extra request headers for this call. |
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.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.locale | string | Locale to save the term in. |
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)
}