Taxonomy

addParams adds several query parameters to the request in one call.

Returns: Taxonomy or TaxonomyQuery. The same object, for chaining.

Validation

• There is no client-side validation. The SDK sends an empty object, empty keys, or parameter names the API does not know as given.
• A missing argument fails to compile. On a Taxonomy, a boolean value fails to compile as well. On a TaxonomyQuery, the inherited signature also accepts boolean values, typed { [key: string]: string | boolean | number }.
• Errors surface on the terminal call that follows, fetch() on a Taxonomy or find() on a TaxonomyQuery, not on addParams(). That call throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. addParams merges the object into the instance's query parameters and makes no request.
• Keeps every parameter you set earlier. A key in paramObj that the instance already holds takes the new value.
• Exists on both objects that stack.taxonomy() returns. On a TaxonomyQuery, it returns the same object typed as Query. See Class-Level Notes on the Taxonomy class page.
• The SDK sends a boolean value as the string true or false.
• Has the same effect as one param call per key.

Example

Basic usage: locale and fallback in one call

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack
    .taxonomy('<TAXONOMY_UID>')
    .addParams({ locale: 'fr-fr', include_fallback: 'true' })
    .fetch<BaseTaxonomy>();
  console.log(result.uid, result.name);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Boolean and number values on the taxonomy list

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

interface BranchedTaxonomy extends BaseTaxonomy {
  _branch?: string;
}

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // stack.taxonomy() accepts boolean values, and the SDK sends them as strings.
  const result = await stack.taxonomy().addParams({ include_branch: true, limit: 5 }).find<BranchedTaxonomy>();
  for (const taxonomy of result.taxonomies ?? []) {
    console.log(taxonomy.uid, 'served from branch', taxonomy._branch);
  }
} catch (error: any) {
  console.error(error);
}

fetch retrieves one published taxonomy by its UID.

Returns: Promise<T>. The requested taxonomy.

Validation

• fetch validates nothing itself. The SDK checks no UID format and sends the UID you passed to stack.taxonomy() as given.
• fetch takes no arguments. Code written for SDK versions earlier than 5.4.0 that passes a locale, as in fetch('fr-fr'), fails to compile with TS2554. Set the locale with the param method instead.
• stack.taxonomy('') never reaches this method, because it returns a TaxonomyQuery, which has no fetch. See the Warning on the Taxonomy class page.
• fetch throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message. A network failure throws an APIError with status set to 0.
• An unknown taxonomy UID fails with HTTP status 404, error code 404, and the error message errors.taxonomy.not_found.

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

Behavior

• Calls GET /taxonomies/{taxonomy_uid} and makes one HTTP request per call.
• Returns the contents of the taxonomy key of the response body. When the body has no taxonomy key, fetch returns the whole body.
• Sends every query parameter that includeFallback, includeBranch, param, and addParams recorded on the instance. A second fetch call on the same instance sends the same request again.
• The taxonomy carries a locale field that names the locale the API served. BaseTaxonomy declares no locale field, so extend it in your own type.
• The generic T types the result for your code. The SDK does not check the response against it. The SDK exports BaseTaxonomy, which declares the common taxonomy fields.

Limitations

• Does not return the terms of the taxonomy. Use the term method to reach them.

Example

Basic usage: read one taxonomy by UID

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy('<TAXONOMY_UID>').fetch<BaseTaxonomy>();
  console.log(result.uid, result.name);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Localized fetch: locale, fallback, and branch on one request

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

// BaseTaxonomy declares neither field, so add the two this request asks for.
interface LocalizedTaxonomy extends BaseTaxonomy {
  locale?: string;
  _branch?: string;
}

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack
    .taxonomy('<TAXONOMY_UID>')
    .param('locale', 'fr-fr')
    .includeFallback()
    .includeBranch()
    .fetch<LocalizedTaxonomy>();
  console.log('Served locale:', result.locale, 'Branch:', result._branch);
} catch (error: any) {
  console.error(error);
}

Edge case: guard against an empty UID

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

const taxonomyUid: string = '';

// An empty UID returns a TaxonomyQuery, which has no fetch, so check it first.
if (!taxonomyUid) {
  console.error('Set a taxonomy UID before calling fetch.');
} else {
  try {
    const result = await stack.taxonomy(taxonomyUid).fetch<BaseTaxonomy>();
    console.log(result.name);
  } catch (error: any) {
    console.error(error);
  }
}

find lists the published taxonomies in the stack.

Returns: Promise<FindResponse<T>>. The published taxonomies.

Validation

• find validates nothing itself.
• find throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message. A network failure throws an APIError with status set to 0.

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

Behavior

• Calls GET /taxonomies and makes one HTTP request per call.
• Returns the response body unchanged. The taxonomies are in its taxonomies array. The body has no count field, even when you chain includeCount.
• Each taxonomy carries a locale field. Send a locale with param('locale', 'fr-fr') to list the taxonomy names in that locale.
• With a locale, the list holds only the taxonomies localized in that locale. Add param('include_fallback', 'true') to list every taxonomy, each with locale set to the locale the API served.
• Sends only the query parameters on the instance: the ones that limit, skip, includeCount, orderByAscending, orderByDescending, param, and addParams record.
• Ignores an encode argument. After an inherited setter such as limit, TypeScript types the chain as Query and accepts find(true). The object is still a TaxonomyQuery, and its find reads no argument.
• A skip value past the end of the list returns an empty taxonomies array.
• Does not page automatically. Combine limit and skip, or use the inherited paginate, next, and previous methods, to read further pages.

Limitations

• Known issue: In 5.3.0 and later, find drops a chained filter, such as where or containedIn, and returns the taxonomy list, with no error. To filter entries by term, call the where method on an entry query with a TaxonomyQueryOperation value.

Example

Basic usage: list the published taxonomies

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy().find<BaseTaxonomy>();
  for (const taxonomy of result.taxonomies ?? []) {
    console.log(taxonomy.uid, taxonomy.name);
  }
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Paging and sorting: the second page of five, newest first

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack
    .taxonomy()
    .orderByDescending('created_at')
    .skip(5)
    .limit(5)
    .find<BaseTaxonomy>();
  console.log('Page 2:', result.taxonomies?.map((taxonomy) => taxonomy.uid));
} catch (error: any) {
  console.error(error);
}

Edge case: a chained filter does not filter, so query entries instead

import contentstack, {
  QueryOperation,
  TaxonomyQueryOperation,
  type BaseEntry,
  type BaseTaxonomy,
} from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // where compiles on stack.taxonomy(), but find never sends the condition.
  const listing = await stack
    .taxonomy()
    .where('taxonomies.<TAXONOMY_UID>', QueryOperation.EQUALS, '<TERM_UID>')
    .find<BaseTaxonomy>();
  console.log('Taxonomies returned:', listing.taxonomies?.length ?? 0);

  // Filter entries by term on an entry query instead.
  const tagged = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .query()
    .where('taxonomies.<TAXONOMY_UID>', TaxonomyQueryOperation.EQ_BELOW, '<TERM_UID>')
    .find<BaseEntry>();
  console.log('Entries tagged with the term or its descendants:', tagged.entries?.length ?? 0);
} catch (error: any) {
  console.error(error);
}

includeBranch asks the API to add the _branch field, which names the branch that served the taxonomy, to the response.

Returns: Taxonomy. The same taxonomy, for chaining.

Validation

• There is nothing to validate. includeBranch takes no arguments and cannot fail.
• Errors surface on the fetch() call that follows, not on includeBranch(). fetch() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. includeBranch sets include_branch to the string 'true' and makes no request. fetch sends the flag.
• The API sets _branch to the branch name, for example main.
• BaseTaxonomy declares no _branch field. Extend it in your own type to read the field without a type error.
• The flag stays on the instance for every later fetch. No method on Taxonomy removes it.

Limitations

• Does not choose a branch. The branch option of the stack configuration does, and the SDK sends it as a branch header on every request.

Example

Basic usage: read the branch that served the taxonomy

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

interface BranchedTaxonomy extends BaseTaxonomy {
  _branch?: string;
}

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy('<TAXONOMY_UID>').includeBranch().fetch<BranchedTaxonomy>();
  console.log(result.uid, 'served from branch', result._branch);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

includeCount sends the include_count flag on the taxonomy list request. GET /taxonomies ignores the flag and returns no count.

Returns: TaxonomyQuery. The same query, for chaining.

Validation

• There is nothing to validate. includeCount takes no arguments and cannot fail.
• Errors surface on the find() call that follows, not on includeCount(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. includeCount sets include_count to the string 'true' and makes no request. find sends the flag.
• The find result has no count field, so result.count is undefined. FindResponse declares count because other endpoints return it. For the parameters the taxonomy list accepts, refer to Get all taxonomies in the Content Delivery API reference.
• Returns the same TaxonomyQuery, which TypeScript types as Query. See Class-Level Notes on the Taxonomy class page.
• A second includeCount call has no further effect. To remove the flag, pass include_count to the removeParam method.

Limitations

• Does not return a total. To find the end of the list, read pages with limit and skip until a page returns fewer taxonomies than the limit.

Example

Basic usage: check for a count before you rely on it

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy().limit(10).includeCount().find<BaseTaxonomy>();
  const returned = result.taxonomies?.length ?? 0;
  // GET /taxonomies returns no count, so result.count is undefined.
  if (result.count === undefined) {
    console.log(`Returned ${returned} taxonomies. The response has no total count.`);
  } else {
    console.log(`Returned ${returned} of ${result.count} taxonomies`);
  }
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

includeFallback returns the taxonomy in an earlier locale in the hierarchy when the taxonomy has no published version in the requested locale.

Returns: Taxonomy. The same taxonomy, for chaining.

Validation

• There is nothing to validate. includeFallback takes no arguments and cannot fail.
• Errors surface on the fetch() call that follows, not on includeFallback(). fetch() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. includeFallback sets include_fallback to the string 'true' and makes no request. fetch sends the flag.
• The flag matters only with a locale. Taxonomy has no locale method, so send one with param('locale', 'fr-fr') through the param method.
• The API resolves the fallback through the locale fallback hierarchy of the branch, not the SDK. The locale field of the returned taxonomy names the locale the API served.
• Without the flag, a missing locale version fails with HTTP status 404, error code 404, and the error message errors.taxonomy.not_found. With the flag, the same request returns the taxonomy in the fallback locale.
• The flag stays on the instance for every later fetch. No method on Taxonomy removes it, so build a new instance to fetch without it.

Limitations

• Does not reach the terms. A Term or TermQuery from the term method starts with no parameters, so chain includeFallback on it as well.

Example

Basic usage: accept an earlier locale when the French version is missing

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack
    .taxonomy('<TAXONOMY_UID>')
    .param('locale', 'fr-fr')
    .includeFallback()
    .fetch<BaseTaxonomy>();
  console.log(result.uid, result.name);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: detect a fallback

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

// BaseTaxonomy declares no locale field, so add the one the response carries.
interface LocalizedTaxonomy extends BaseTaxonomy {
  locale?: string;
}

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

const requested = 'fr-fr';

try {
  const result = await stack
    .taxonomy('<TAXONOMY_UID>')
    .param('locale', requested)
    .includeFallback()
    .fetch<LocalizedTaxonomy>();

  // The locale field names the locale the API served.
  if (result.locale && result.locale !== requested) {
    console.log(`No ${requested} version, served ${result.locale} instead`);
  }
} catch (error: any) {
  console.error(error);
}

limit caps the number of taxonomies the response contains.

Returns: TaxonomyQuery. The same query, for chaining.

Validation

• There is no client-side validation. The SDK sends zero, a negative number, or a fraction as given.
• A missing argument or a string argument fails to compile, because key is a required number.
• Errors surface on the find() call that follows, not on limit(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. limit sets the limit query parameter and makes no request. find sends the value.
• Returns the same TaxonomyQuery, which TypeScript types as Query. See Class-Level Notes on the Taxonomy class page.
• A second limit call replaces the first value. A later param('limit', ...) or paginate call also replaces it, because all three write the same key.
• Without limit, the SDK sends no limit parameter.

Example

Basic usage: return at most ten taxonomies

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy().limit(10).find<BaseTaxonomy>();
  console.log('Returned', result.taxonomies?.length ?? 0, 'taxonomies');
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: a later param call replaces the limit

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // Both calls write the limit key, so this request sends limit=2.
  const result = await stack.taxonomy().limit(10).param('limit', 2).find<BaseTaxonomy>();
  console.log('Returned', result.taxonomies?.length ?? 0, 'taxonomies');
} catch (error: any) {
  console.error(error);
}

orderByAscending sorts the taxonomies by a field, lowest value first.

Returns: TaxonomyQuery. The same query, for chaining.

Validation

• There is no client-side validation. The SDK sends an empty string or an unknown field UID as given.
• A missing argument fails to compile, because key is a required string.
• Errors surface on the find() call that follows, not on orderByAscending(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. orderByAscending sets the asc query parameter to the field UID and makes no request. find sends the value.
• Returns the same TaxonomyQuery, which TypeScript types as Query. See Class-Level Notes on the Taxonomy class page.
• A second orderByAscending call replaces the first field. The query stores one asc value.
• The API sorts taxonomies by fields such as name, created_at, and uid.

Limitations

• Does not clear a descending sort. After orderByDescending, the request carries both asc and desc, and the API applies desc. Remove desc with the removeParam method to sort in ascending order.

Example

Basic usage: oldest taxonomies first

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy().orderByAscending('created_at').find<BaseTaxonomy>();
  for (const taxonomy of result.taxonomies ?? []) {
    console.log(taxonomy.created_at, taxonomy.uid);
  }
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: switch from a descending to an ascending sort

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const query = stack.taxonomy().orderByDescending('updated_at');

  // Drop desc first, or the request carries both sort keys.
  const result = await query.removeParam('desc').orderByAscending('updated_at').find<BaseTaxonomy>();
  console.log(result.taxonomies?.map((taxonomy) => taxonomy.uid));
} catch (error: any) {
  console.error(error);
}

orderByDescending sorts the taxonomies by a field, highest value first.

Returns: TaxonomyQuery. The same query, for chaining.

Validation

• There is no client-side validation. The SDK sends an empty string or an unknown field UID as given.
• A missing argument fails to compile, because key is a required string.
• Errors surface on the find() call that follows, not on orderByDescending(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. orderByDescending sets the desc query parameter to the field UID and makes no request. find sends the value.
• Returns the same TaxonomyQuery, which TypeScript types as Query. See Class-Level Notes on the Taxonomy class page.
• A second orderByDescending call replaces the first field. The query stores one desc value.
• The API sorts taxonomies by fields such as name, created_at, and uid.

Limitations

• Does not clear an ascending sort. After orderByAscending, the request carries both asc and desc, and the API applies desc whichever call comes first. Remove asc with the removeParam method when you no longer need it.

Example

Basic usage: most recently updated taxonomies first

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy().orderByDescending('updated_at').limit(5).find<BaseTaxonomy>();
  for (const taxonomy of result.taxonomies ?? []) {
    console.log(taxonomy.updated_at, taxonomy.uid);
  }
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

param adds one query parameter to the request.

Returns: Taxonomy or TaxonomyQuery. The same object, for chaining.

Validation

• There is no client-side validation. The SDK sends an empty key, an empty value, or a parameter name the API does not know as given.
• A missing argument, or a value that is neither a string nor a number, fails to compile.
• Errors surface on the terminal call that follows, fetch() on a Taxonomy or find() on a TaxonomyQuery, not on param(). That call throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. param records the pair in the instance's query parameters and makes no request.
• Exists on both objects that stack.taxonomy() returns. On a TaxonomyQuery, it returns the same object typed as Query. See Class-Level Notes on the Taxonomy class page.
• Shares one set of keys with the dedicated setters. param('limit', 5) and limit(5) write the same key, so the later call wins.
• Use param for a Delivery API query parameter that has no dedicated method, such as locale. Prefer the dedicated method when one exists, because its name states the intent.
• The SDK encodes the value for the URL, so a value with a space or an ampersand needs no encoding from you.
• Use the addParams method to set several parameters in one call.

Example

Basic usage: read a taxonomy in another locale

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy('<TAXONOMY_UID>').param('locale', 'fr-fr').fetch<BaseTaxonomy>();
  console.log('Name in French:', result.name);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Number value: cap the taxonomy list

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // On stack.taxonomy(), param writes the same limit key that limit() writes.
  const result = await stack.taxonomy().param('limit', 3).find<BaseTaxonomy>();
  console.log('Returned', result.taxonomies?.length ?? 0, 'taxonomies');
} catch (error: any) {
  console.error(error);
}

removeParam deletes one query parameter that an earlier call set on the query.

Returns: TaxonomyQuery. The same query, for chaining.

Validation

• There is no client-side validation. A key that the query does not hold changes nothing and raises no error.
• A missing argument fails to compile, because key is a required string.
• Errors surface on the find() call that follows, not on removeParam(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. removeParam deletes the key from the query's parameter object and makes no request.
• Takes the query parameter name, not the method name. Remove include_count to undo includeCount, asc to undo orderByAscending, and desc to undo orderByDescending.
• Returns the same TaxonomyQuery, which TypeScript types as Query. See Class-Level Notes on the Taxonomy class page.
• Exists only on stack.taxonomy(). A Taxonomy from stack.taxonomy('<TAXONOMY_UID>') has no removeParam.

Limitations

• Removes only what this query holds. The SDK adds environment, and locale when the stack configuration sets one, to every request from the stack configuration, so removeParam cannot remove them.

Example

Basic usage: reuse a query without the sort

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const query = stack.taxonomy().limit(5).orderByDescending('created_at');
  const sorted = await query.find<BaseTaxonomy>();
  console.log('Sorted by created_at, descending:', sorted.taxonomies?.map((taxonomy) => taxonomy.uid));

  // The same query, sent again without desc.
  const unsorted = await query.removeParam('desc').find<BaseTaxonomy>();
  console.log('Default order:', unsorted.taxonomies?.map((taxonomy) => taxonomy.uid));
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

skip sets the number of taxonomies the response leaves out from the start of the list.

Returns: TaxonomyQuery. The same query, for chaining.

Validation

• There is no client-side validation. The SDK sends zero, a negative number, or a fraction as given.
• A missing argument or a string argument fails to compile, because key is a required number.
• Errors surface on the find() call that follows, not on skip(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. skip sets the skip query parameter and makes no request. find sends the value.
• Returns the same TaxonomyQuery, which TypeScript types as Query. See Class-Level Notes on the Taxonomy class page.
• A second skip call replaces the first value. paginate, next, and previous write the same key, so a later call to one of them replaces it too.
• Without skip, the SDK sends no skip parameter.
• A skip value past the end of the list returns an empty taxonomies array.
• Pair skip with limit to read one fixed-size page at a time. The API returns no count on this endpoint, so stop when a page returns fewer taxonomies than the limit.

Example

Basic usage: read the third page of ten taxonomies

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy().skip(20).limit(10).find<BaseTaxonomy>();
  console.log('Page 3:', result.taxonomies?.map((taxonomy) => taxonomy.uid));
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Paging: read every taxonomy, one page at a time

import contentstack, { type BaseTaxonomy } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

const pageSize = 25;
const all: BaseTaxonomy[] = [];

try {
  let done = false;
  while (!done) {
    const page = await stack.taxonomy().skip(all.length).limit(pageSize).find<BaseTaxonomy>();
    const taxonomies = page.taxonomies ?? [];
    all.push(...taxonomies);
    // The API returns no count here, so a short page marks the end of the list.
    done = taxonomies.length < pageSize;
  }
  console.log('Read', all.length, 'taxonomies');
} catch (error: any) {
  console.error(error);
}

term returns a Term for one term of this taxonomy, or a TermQuery across all of its terms, depending on whether you pass a term UID.

Returns: Term or TermQuery. A single term, or a query across the taxonomy's terms.

Instance State

term declares two overloads, and the argument decides which class you get.

• Call term('<TERM_UID>') to work with one term. This returns a Term, which has methods such as fetch and ancestors.
• Call term() without a UID to list the terms of the taxonomy. This returns a TermQuery, which has methods such as find and locale.

TypeScript rejects a method from the other class at compile time with TS2339, for example term().fetch().

Known issue In 5.x, term('') compiles as a Term, but an empty UID returns a TermQuery, so a later fetch(), locales(), ancestors(), or descendants() throws a TypeError. Check that a term UID variable is non-empty before you pass it.

Validation

• There is no client-side validation. The SDK checks no UID format, and an unknown term UID raises no error at this step.
• Errors surface on the terminal call that follows, not on term(). The terminal calls are fetch(), locales(), ancestors(), and descendants() on a Term, and find() on a TermQuery.
• Each terminal call throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.

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

Behavior

• Client-side only. term builds a new Term or TermQuery and makes no request.
• Returns a new object on every call, each with an empty set of query parameters.

Limitations

• Does not pass the parameters of the Taxonomy to the term request. term passes only the taxonomy UID to the new object. Flags and parameters chained on the Taxonomy, such as includeFallback or a locale set through param, stay on the Taxonomy. Chain them on the Term or TermQuery instead.

Example

Basic usage: read one term

import contentstack, { type BaseTerm } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy('<TAXONOMY_UID>').term('<TERM_UID>').fetch<BaseTerm>();
  console.log(result.uid, result.name, 'depth', result.depth);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

No UID: list the terms of the taxonomy

import contentstack, { type BaseTerm } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  const result = await stack.taxonomy('<TAXONOMY_UID>').term().find<BaseTerm>();
  for (const term of result.terms ?? []) {
    console.log(term.uid, term.name);
  }
} catch (error: any) {
  console.error(error);
}

Edge case: set the locale on the term, not on the taxonomy

import contentstack, { type BaseTerm } from '@contentstack/delivery-sdk';

const stack = contentstack.stack({
  apiKey: '<API_KEY>',
  deliveryToken: '<DELIVERY_TOKEN>',
  environment: '<ENVIRONMENT>',
});

try {
  // A locale chained on the taxonomy does not reach the term request.
  const taxonomy = stack.taxonomy('<TAXONOMY_UID>').param('locale', 'fr-fr');

  // Chain it on the term as well.
  const result = await taxonomy
    .term('<TERM_UID>')
    .param('locale', 'fr-fr')
    .includeFallback()
    .fetch<BaseTerm>();
  console.log(result.uid, result.name);
} catch (error: any) {
  console.error(error);
}