Entry

addParams merges several query parameters into the request at once.

Returns: Entry or Entries. The same object, for chaining.

Validation

• There is no client-side validation. addParams accepts any key, including keys that other methods set.
• The two forms accept different value types, and TypeScript enforces the difference. Entry accepts string arrays but not booleans. Entries accepts booleans but not arrays.
• Errors surface on the fetch() or find() call that follows, not on addParams(). Those calls throw 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 keys into the stored query parameters and makes no request. A key that already exists takes the new value.
• addParams builds a new parameter object instead of changing the existing one. On Entries, a Query created earlier with the query method keeps the old object, so the new keys do not reach that query.
• On Entry, addParams returns the Entry.
• Known issue: In 5.x, on Entries, methods such as includeReference and query do not compile after addParams, because TypeScript types the return value as Query. Call the Entries methods before addParams, as Chain order on the Entry class page describes.
• Use addParams for API parameters that have no method of their own. To set one key, use the param method on Entries.

Example

Basic usage: set two parameters on a single entry

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .addParams({ locale: 'en-us', include_fallback: 'true' })
    .fetch();
  console.log(result);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

List form: pass number and boolean values

import contentstack from '@contentstack/delivery-sdk';

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

try {
  // Entries accepts booleans and numbers. addParams comes last because it returns a Query type.
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .addParams({ include_count: true, limit: 5 })
    .find();
  console.log(result.count, result.entries?.length);
} catch (error: any) {
  console.error(error);
}

assetFields asks the API to add extra field groups to the assets that the entry includes.

Returns: Entry or Entries. The same object, for chaining.

Validation

• There is no client-side validation. assetFields accepts any string.
• A call with no arguments compiles, because the parameter is a rest parameter. It writes nothing and logs nothing.
• Errors surface on the fetch() or find() call that follows, not on assetFields(). Those calls throw 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. assetFields stores the names under the asset_fields[] query parameter and makes no request. The fetch() or find() call that follows sends them.
• A second call replaces the first list. Calls do not add up, unlike the includeReference method. Pass every name in one call.
• The Content Delivery API accepts two group names, visual_markups and user_defined_fields. The SDK does not check the names, so it also forwards any other name.
• The API returns the groups only for included assets managed in New Assets. An included asset stored directly in the stack comes back without the visual_markups and user_defined_fields keys.
• assetFields works the same way on Entry and Entries.

Note The SDK's code comments also name embedded_metadata and ai_generated_metadata. The API rejects both with status 422 and error_code 141, so the request throws an APIError.

Example

Basic usage: add one asset field group to a single entry

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .assetFields('visual_markups')
    .fetch();
  console.log(result);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Several groups: add two asset field groups to a list

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .assetFields('user_defined_fields', 'visual_markups')
    .find();
  console.log(result.entries?.length);
} catch (error: any) {
  console.error(error);
}

except leaves the named fields out of the response.

Returns: Entry or Entries. The same object, for chaining.

Validation

• There is no client-side validation. The SDK sends an empty string or an unknown field UID as given. An empty array writes nothing.
• Errors surface on the fetch() or find() call that follows, not on except(). Those calls throw 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. except stores the field UIDs as query parameters and makes no request.
  • A string goes under the key except[BASE][].
  • An array goes under indexed keys: except[BASE][0], except[BASE][1], and so on.
• Calls overwrite rather than add up.
  • A second string call replaces the first string.
  • A second array call overwrites the same indexes, starting from 0. Pass every field in one array.
  • A string call and an array call write different keys, so the request carries both.
• The BASE scope covers the entry's own fields. except takes no argument for the fields of referenced entries.
  • To drop fields of a referenced entry, pass the except[<reference_field_uid>][] key through the addParams method, together with includeReference. For example, addParams({ 'except[author][]': 'title' }) drops the title of each resolved author entry.
• except works the same way on Entry and Entries. The only method does the opposite.

Example

Basic usage: leave out one field of a single entry

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .except('url')
    .fetch();
  console.log(result);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Several fields: pass one array on a list

import contentstack from '@contentstack/delivery-sdk';

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

try {
  // Pass every field in one array. A second array call overwrites the first.
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .except(['title', 'url'])
    .find();
  console.log(result.entries);
} catch (error: any) {
  console.error(error);
}

fetch reads one published entry by its UID and returns the entry object.

Returns: Promise<T>. The requested entry.

Validation

• There is no client-side validation. fetch sends whatever content type UID and entry UID the chain holds.
• fetch exists only on Entry. Calling it on entry() without a UID is a compile error.
• fetch throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.
  • An unknown entry UID throws status 422 with error_code 141.
  • An unknown content type UID throws status 422 with error_code 118.
  • A network failure throws status 0, with the Node error code (for example ENOTFOUND) in error_code.

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

Behavior

• One call sends one GET /content_types/{content_type_uid}/entries/{entry_uid} request, with every parameter the chain set.
• fetch returns the value of the response's entry key, not the whole response body. Any other top-level key the API returns beside entry does not reach your code. When the response has no entry key, fetch returns the whole body.
• fetch is generic. Pass an interface as T, for example one that extends the exported BaseEntry, to type the result. The SDK does not check the response against T.
• When the chain called the variants method, fetch sends the x-cs-variant-uid header, and the branch header when you passed a branch name.

Limitations

• Does not return content type details. The API sends them beside entry, and fetch keeps only entry. Call the includeContentType method on entry() and read content_type from find instead.

Example

Basic usage: read one entry by UID

import contentstack from '@contentstack/delivery-sdk';

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

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

Typed result: read an entry into your own interface

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

interface BlogPost extends BaseEntry {
  url: string;
}

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

try {
  const post = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .locale('en-us')
    .fetch<BlogPost>();
  console.log(post.title, post.url, post._version);
} catch (error: any) {
  console.error(error);
}

Error handling: an unknown entry UID

import contentstack from '@contentstack/delivery-sdk';

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

try {
  await stack.contentType('<CONTENT_TYPE_UID>').entry('blt0000000000000000').fetch();
} catch (error: any) {
  // The API rejects an entry UID that does not exist with status 422 and error_code 141.
  if (error.status === 422 && error.error_code === 141) {
    console.error('No published entry with that UID in this environment.');
  } else {
    console.error(error);
  }
}

find sends the list request and returns the matching entries of the content type.

Returns: Promise<FindResponse<T>>. The matching entries.

Validation

• There is no client-side validation. find sends whatever parameters the chain holds.
• find exists only on Entries. Calling it on entry('<ENTRY_UID>') is a compile error.
• find throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message.
  • An unknown content type UID throws status 422 with error_code 118.
  • A network failure throws status 0, with the Node error code (for example ENOTFOUND) in error_code.

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

Behavior

• One call sends one GET /content_types/{content_type_uid}/entries request and returns one page. The SDK does not iterate pages. See Pagination on the Entry class page.
• find returns the whole response body as a FindResponse<T>. The entries are in entries, the total is in count when you chain includeCount, and the content type is in content_type when you chain includeContentType. Each key is optional, because the API includes only what you asked for.
• find is generic. Pass an interface as T, for example one that extends the exported BaseEntry, to type each item in entries. The SDK does not check the response against T.
• find adds a query parameter only when filter conditions exist. Entries has no filter methods, so conditions come from a Query created with the query method, which writes to the same object.
• encode acts only on those conditions.
• When the chain called the variants method, find sends the x-cs-variant-uid header, and the branch header when you passed a branch name.

Limitations

• Does not return every entry when you omit limit. The default page size is 100 entries, and the maximum page size is 250 entries. Chain the includeCount method and page with skip and limit.
• Known issue: In 5.x, find(true) can return no results for a value that contains a space or a symbol such as & or /. It also breaks conditions that hold a list, such as containedIn, tags, and and or. Call find() instead.

Example

Basic usage: list the entries of a content type

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().find();
  console.log(result.entries?.length);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Typed result: list entries into your own interface

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

interface BlogPost extends BaseEntry {
  url: string;
}

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().limit(5).find<BlogPost>();
  result.entries?.forEach((post) => console.log(post.title, post.url));
} catch (error: any) {
  console.error(error);
}

All parameters: leave encode off

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const entries = stack.contentType('<CONTENT_TYPE_UID>').entry();
  // The query writes its condition into the object that entries also holds.
  entries.query().equalTo('title', 'Home & Garden');
  // Pass false for the encode parameter.
  const result = await entries.find(false);
  console.log(result.entries?.length);
} catch (error: any) {
  console.error(error);
}

includeBranch asks the API to include the name of the branch that holds the content in the response.

Returns: Entry or Entries. The same object, for chaining.

Validation

• Errors surface on the fetch() or find() call that follows, not on includeBranch(). Those calls throw 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 the include_branch query parameter to 'true' and makes no request. The fetch() or find() call that follows sends it.
• The API adds a _branch key to each entry object, not to the top level of the response. It holds the branch UID, for example "_branch": "main". On fetch(), the key appears on the returned entry. On find(), it appears on each item in entries.
• includeBranch reports the branch. It does not choose one. The branch option on the stack configuration, or the branchName argument of the variants method, picks the branch to read.
• includeBranch works the same way on Entry and Entries.
• Calling it twice changes nothing. The SDK stores the flag under one key.

Example

Basic usage: read one entry with its branch name

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .includeBranch()
    .fetch();
  console.log(result);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

List form: list entries with their branch name

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().includeBranch().find();
  console.log(result.entries);
} catch (error: any) {
  console.error(error);
}

includeContentType asks the API to return the details of the content type together with the entries.

Returns: Entry or Entries. The same object, for chaining.

Validation

• Errors surface on the fetch() or find() call that follows, not on includeContentType(). Those calls throw 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. includeContentType sets the include_content_type query parameter to 'true' and makes no request.
• The two forms differ in what reaches your code.
  • On Entries, find returns the whole response body, so the content type is in the content_type key of the result.
  • On Entry, fetch returns only the response's entry key. The content type the API sends beside it does not reach your code.
• Calling it twice changes nothing. The SDK stores the flag under one key.

Limitations

• Does not return the content type from fetch on a single entry. Use entry().includeContentType() with find, or fetch the content type with stack.contentType('<CONTENT_TYPE_UID>').fetch() instead.

Example

Basic usage: list entries with their content type

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .includeContentType()
    .find();
  console.log(result.content_type, result.entries?.length);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Edge case: fetch returns the entry without the content type

import contentstack from '@contentstack/delivery-sdk';

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

try {
  // fetch() keeps only the entry, so read the content type separately.
  const entry = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').includeContentType().fetch();
  const contentType = await stack.contentType('<CONTENT_TYPE_UID>').fetch();
  console.log(entry, contentType);
} catch (error: any) {
  console.error(error);
}

includeCount adds the total number of matching entries to the find response.

Returns: Entries. The same query, for chaining.

Validation

• 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 the include_count query parameter to 'true' and makes no request. find then returns a count key beside entries.
• count is the total number of matching entries, not the number on this page. Compare it with the length of entries to find out whether more pages remain.
• Calling it twice changes nothing. The SDK stores the flag under one key.
• Known issue: In 5.x, includeReference, query, and the other Entries methods do not compile after includeCount, because TypeScript types the return value as Query. Call the Entries methods before includeCount, as Chain order on the Entry class page describes.

Example

Basic usage: get the total number of entries with the first page

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().includeCount().find();
  console.log('total:', result.count, 'on this page:', result.entries?.length);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Pagination: check whether more entries remain

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const pageSize = 10;
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().limit(pageSize).includeCount().find();
  const returned = result.entries?.length ?? 0;
  console.log('more pages remain:', (result.count ?? 0) > returned);
} catch (error: any) {
  console.error(error);
}

includeEmbeddedItems asks the API to return the entries and assets embedded in the entry's rich text fields, in full.

Returns: Entry or Entries. The same object, for chaining.

Validation

• Errors surface on the fetch() or find() call that follows, not on includeEmbeddedItems(). Those calls throw 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. includeEmbeddedItems sets the include_embedded_items[] query parameter to 'BASE' and makes no request. The fetch() or find() call that follows sends it.
• The value is always BASE, the scope of the entry's own fields. includeEmbeddedItems takes no argument to name another scope.
• The API adds an _embedded_items key to each entry object. It maps each rich text field UID to the list of entries and assets embedded in that field. An entry with nothing embedded gets an empty object, {}.
• includeEmbeddedItems works the same way on Entry and Entries.
• Calling it twice changes nothing. The SDK stores the value under one key.

Example

Basic usage: read one entry with its embedded items

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .includeEmbeddedItems()
    .fetch();
  console.log(result);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

List form: list entries with their embedded items

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().includeEmbeddedItems().find();
  console.log(result.entries?.length);
} catch (error: any) {
  console.error(error);
}

includeFallback asks the API to return content from the fallback language when the entry has no published version in the requested locale.

Returns: Entry or Entries. The same object, for chaining.

Validation

• Errors surface on the fetch() or find() call that follows, not on includeFallback(). Those calls throw 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 the include_fallback query parameter to 'true' and makes no request. The fetch() or find() call that follows sends it.
• The flag matters when you also request a locale with the locale method. When an entry has no published version in that locale, the API returns the version from the fallback language that the stack sets for that locale.
• Without a locale, the flag changes nothing. The API returns the master locale, as it does without the flag.
• includeFallback works the same way on Entry and Entries. On Entries, it applies to every entry in the result.
• Calling it twice changes nothing. The SDK stores the flag under one key.

Example

Basic usage: read one entry in French with fallback

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

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .locale('fr-fr')
    .includeFallback()
    .fetch<BaseEntry>();
  // result.locale names the language the API actually returned.
  console.log(result.title, result.locale);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

List form: apply fallback to every entry in the list

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

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .locale('fr-fr')
    .includeFallback()
    .find<BaseEntry>();
  result.entries?.forEach((entry) => console.log(entry.uid, entry.locale));
} catch (error: any) {
  console.error(error);
}

includeMetadata asks the API to include the entry metadata in the response.

Returns: Entry or Entries. The same object, for chaining.

Validation

• Errors surface on the fetch() or find() call that follows, not on includeMetadata(). Those calls throw 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. includeMetadata sets the include_metadata query parameter to 'true' and makes no request. The fetch() or find() call that follows sends it.
• The API adds a _metadata key to each entry object. It holds the metadata that extensions attach to the entry, under extensions and keyed by extension UID. An entry with no extension metadata gets an empty object, {}.
• includeMetadata works the same way on Entry and Entries.
• Calling it twice changes nothing. The SDK stores the flag under one key.

Example

Basic usage: read one entry with its metadata

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .includeMetadata()
    .fetch();
  console.log(result);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

List form: list entries with their metadata

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().includeMetadata().find();
  console.log(result.entries);
} catch (error: any) {
  console.error(error);
}

includeReference asks the API to return the entries in the named reference fields in full, instead of as UIDs.

Returns: Entry or Entries. The same object, for chaining.

Validation

• Calling includeReference() with no arguments compiles, because the parameter is a rest parameter. The SDK logs an error with console.error and returns the object unchanged. It does not throw.
• There is no other client-side validation. includeReference does not check that a field exists or that it is a reference field.
• The API ignores a UID that the content type does not have. The request succeeds and returns the entry without that reference resolved.
• Errors surface on the fetch() or find() call that follows, not on includeReference(). Those calls throw 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. includeReference adds each UID to the include[] query parameter and makes no request. The fetch() or find() call that follows sends it.
• Arguments can mix strings and arrays. includeReference('author', ['category', 'related_posts']) adds three UIDs.
• Calls add up. A second call appends its UIDs to the ones already stored.
• Without it, each value in a reference field holds only the referenced entry's uid and _content_type_uid.
• A dot path resolves a reference inside a referenced entry. includeReference('author', 'author.books') returns each author with its books field resolved to full entries. With 'author' alone, books holds only uid and _content_type_uid.
• includeReference works the same way on Entry and Entries.
• Each resolved reference keeps its _content_type_uid key, so you can tell which content type it comes from.

Example

Basic usage: resolve one reference field

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .includeReference('author')
    .fetch();
  console.log(result);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

All parameters: resolve several reference fields on a list

import contentstack from '@contentstack/delivery-sdk';

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

try {
  // Strings and arrays can be mixed. Calls add up.
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .includeReference('author', ['category', 'related_posts'])
    .find();
  console.log(result.entries?.length);
} catch (error: any) {
  console.error(error);
}

includeReferenceContentTypeUID asks the API to add the content type UID to each referenced entry in the response.

Returns: Entries. The same query, for chaining.

Validation

• Errors surface on the find() call that follows, not on includeReferenceContentTypeUID(). 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. includeReferenceContentTypeUID sets the include_reference_content_type_uid query parameter to 'true' and makes no request. find sends it.
• The API already returns _content_type_uid on each reference, resolved or not, without this flag. Adding the flag leaves the response unchanged.
• includeReferenceContentTypeUID exists only on Entries. Calling it on entry('<ENTRY_UID>') is a compile error.
• Calling it twice changes nothing. The SDK stores the flag under one key.

Example

Basic usage: list entries with resolved references and their content type UIDs

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .includeReference('author')
    .includeReferenceContentTypeUID()
    .find();
  console.log(result.entries);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

includeSchema asks the API to return the schema of the content type together with the entries.

Returns: Entries. The same query, for chaining.

Validation

• Errors surface on the find() call that follows, not on includeSchema(). 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. includeSchema sets the include_schema query parameter to 'true' and makes no request. find sends it.
• The API returns the schema in a top-level schema key, beside entries. It holds the array of field definitions of the content type.
• FindResponse declares no field for the schema, so TypeScript does not type it. Read the extra key from the result with a cast.
• The includeContentType method returns the full content type in the typed content_type key instead.
• includeSchema exists only on Entries. Calling it on entry('<ENTRY_UID>') is a compile error.
• Calling it twice changes nothing. The SDK stores the flag under one key.

Example

Basic usage: list entries with the content type schema

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().includeSchema().find();
  // The schema arrives as an extra top-level key that FindResponse does not declare.
  console.log(Object.keys(result as Record<string, unknown>));
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

limit caps the number of entries the response contains.

Returns: Entries. The same query, for chaining.

Validation

• There is no client-side validation. The SDK sends zero, a negative number, or a fraction as given.
• 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 it.
• Omitting limit does not return every entry. The default page size is 100 entries. See Pagination on the Entry class page.
• The API returns at most 250 entries per request. It caps a larger value at 250 and does not reject it.
• Calling it twice replaces the first value. The paginate method also writes limit, so whichever runs last sets the value.
• Known issue: In 5.x, includeReference, query, and the other Entries methods do not compile after limit, because TypeScript types the return value as Query. Call the Entries methods before limit, as Chain order on the Entry class page describes.

Example

Basic usage: return at most ten entries

import contentstack from '@contentstack/delivery-sdk';

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

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

Chain order: call Entries methods before limit

import contentstack from '@contentstack/delivery-sdk';

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

try {
  // Compiles and runs: the Entries method comes first.
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().includeReference('author').limit(10).find();
  console.log(result.entries?.length);

  // Does not compile: after limit(), TypeScript treats the chain as a Query.
  // stack.contentType('<CONTENT_TYPE_UID>').entry().limit(10).includeReference('author');
} catch (error: any) {
  console.error(error);
}

locale sets the language in which to read the entry or entries.

Returns: Entry or Entries. The same object, for chaining.

Validation

• There is no client-side validation. The SDK sends an empty string or an unknown locale code as given.
  • The API treats an empty string as no locale and returns the master locale.
  • A locale code the stack does not have fails with status 422 and error_code 141. The includeFallback method does not prevent it.
• Errors surface on the fetch() or find() call that follows, not on locale(). Those calls throw 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. locale sets the locale query parameter and makes no request. The fetch() or find() call that follows sends it.
• Without locale, the API returns the stack's master locale.
• Calling it twice replaces the first value. The SDK stores the locale under one key.
• locale works the same way on Entry and Entries. Pair it with the includeFallback method to get content from the fallback language when an entry has no published version in the requested locale.

Example

Basic usage: read one entry in a specific locale

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

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .locale('en-us')
    .fetch<BaseEntry>();
  console.log(result.title, result.locale);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

List form: list the entries of one locale

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

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().locale('en-us').find<BaseEntry>();
  result.entries?.forEach((entry) => console.log(entry.title));
} catch (error: any) {
  console.error(error);
}

only limits the response to the named fields.

Returns: Entry or Entries. The same object, for chaining.

Validation

• There is no client-side validation. The SDK sends an empty string or an unknown field UID as given. An empty array writes nothing.
• Errors surface on the fetch() or find() call that follows, not on only(). Those calls throw 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. only stores the field UIDs as query parameters and makes no request.
  • A string goes under the key only[BASE][].
  • An array goes under indexed keys: only[BASE][0], only[BASE][1], and so on.
• Calls overwrite rather than add up.
  • A second string call replaces the first string.
  • A second array call overwrites the same indexes, starting from 0. Pass every field in one array.
  • A string call and an array call write different keys, so the request carries both.
• The BASE scope covers the entry's own fields. only takes no argument for the fields of referenced entries.
  • To keep fields of a referenced entry, pass the only[<reference_field_uid>][] key through the addParams method, together with includeReference. For example, addParams({ 'only[author][]': 'title' }) keeps only the title of each resolved author entry.
• only works the same way on Entry and Entries. The except method does the opposite.

Example

Basic usage: keep only the title of a single entry

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .only('title')
    .fetch();
  console.log(result);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Several fields: pass one array on a list

import contentstack from '@contentstack/delivery-sdk';

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

try {
  // Pass every field in one array. A second array call overwrites the first.
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .only(['title', 'url'])
    .find();
  console.log(result.entries);
} catch (error: any) {
  console.error(error);
}

orderByAscending sorts the entries in ascending order of the named field.

Returns: Entries. 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.
• 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 it.
• Without a sort method, the API applies its own default order.
• Calling it twice replaces the first field. The SDK stores it under one key, so you can sort by one field only.
• orderByAscending does not clear a sort that the orderByDescending method set, which uses a different key. Call the removeParam method with 'desc' to drop it.
• Known issue: In 5.x, includeReference, query, and the other Entries methods do not compile after orderByAscending, because TypeScript types the return value as Query. Call the Entries methods before orderByAscending, as Chain order on the Entry class page describes.

Example

Basic usage: sort entries by a field in ascending order

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

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().orderByAscending('updated_at').find<BaseEntry>();
  result.entries?.forEach((entry) => console.log(entry.updated_at, entry.title));
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

orderByDescending sorts the entries in descending order of the named field.

Returns: Entries. 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.
• 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 it.
• Without a sort method, the API applies its own default order.
• Calling it twice replaces the first field. The SDK stores it under one key, so you can sort by one field only.
• orderByDescending does not clear a sort that the orderByAscending method set, which uses a different key. Call the removeParam method with 'asc' to drop it.
• Known issue: In 5.x, includeReference, query, and the other Entries methods do not compile after orderByDescending, because TypeScript types the return value as Query. Call the Entries methods before orderByDescending, as Chain order on the Entry class page describes.

Example

Basic usage: sort entries by a field in descending order

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

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().orderByDescending('updated_at').find<BaseEntry>();
  result.entries?.forEach((entry) => console.log(entry.updated_at, entry.title));
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

param sets one query parameter on the request.

Returns: Entries. The same query, for chaining.

Validation

• There is no client-side validation. param accepts any key, including keys that other methods set.
• Errors surface on the find() call that follows, not on param(). 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. param stores the value under key and makes no request. find sends it.
• A key that already exists takes the new value, whichever method set it. For example, param('limit', 5) replaces an earlier limit(10).
• Use param for an API parameter that has no method of its own. To set several keys at once, use the addParams method.
• Known issue: In 5.x, includeReference, query, and the other Entries methods do not compile after param, because TypeScript types the return value as Query. Call the Entries methods before param, as Chain order on the Entry class page describes.

Example

Basic usage: set one query parameter

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().param('locale', 'en-us').find();
  console.log(result.entries?.length);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Numeric value: set the page size through param

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().param('limit', 5).find();
  console.log(result.entries?.length);
} catch (error: any) {
  console.error(error);
}

query opens a Query over the same entries, so you can filter them by field values.

Returns: Query. A query over the same entries.

Validation

• There is no client-side validation. query passes queryObj through without checking its keys or operators.
• Errors surface on the find() call that follows, not on query(). find() throws an APIError when the request fails, carrying the HTTP status, the API error_code, and the error_message. A malformed condition in queryObj reaches the API and fails there.

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

Behavior

• Client-side only. query returns a new Query and makes no request. The Query sends its request to the same content type endpoint as find on Entries.
• The Query uses the same parameter objects as the Entries that created it, so methods called on the Entries before query() carry into the query. See Shared state on the Query class page.
• queryObj takes conditions in the API's JSON query form, for example { title: 'Home' } or { updated_at: { $gte: '2026-01-01' } }. The Query merges it into a copy of the existing conditions.
• The Query copies the variant UIDs and branch name when query() runs. Call the variants method before query().
• Query has no includeReference, locale, or other response-shaping methods. Call them on the Entries before query().

Example

Basic usage: filter entries by a field value

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

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .query()
    .where('title', QueryOperation.EQUALS, 'Home')
    .find();
  console.log(result.entries?.length);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

All parameters: start the query from a raw condition

import contentstack from '@contentstack/delivery-sdk';

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

try {
  // queryObj uses the API's JSON query form.
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .query({ updated_at: { $gte: '2026-01-01' } })
    .find();
  console.log(result.entries?.length);
} catch (error: any) {
  console.error(error);
}

Chain order: shape the response before opening the query

import contentstack from '@contentstack/delivery-sdk';

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

try {
  // includeReference and locale exist on Entries, not on Query, so they come first.
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .includeReference('author')
    .locale('en-us')
    .query()
    .exists('title')
    .limit(10)
    .find();
  console.log(result.entries?.length);
} catch (error: any) {
  console.error(error);
}

removeParam deletes one query parameter from the request.

Returns: Entries. The same query, for chaining.

Validation

• There is no client-side validation. Removing a key that the chain never set does nothing.
• 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 key from the stored query parameters and makes no request.
• removeParam clears parameters that methods such as limit, locale, or includeCount set. It does not clear filter conditions that a Query added, because the SDK stores those separately.
• It cannot remove the environment parameter. The stack configuration sends that value on every request.
• A Query created from these Entries shares the same parameters, so the removal applies to that query too. See Shared state on the Query class page.
• Known issue: In 5.x, includeReference, query, and the other Entries methods do not compile after removeParam, because TypeScript types the return value as Query. Call the Entries methods before removeParam, as Chain order on the Entry class page describes.

Example

Basic usage: drop a parameter set earlier in the chain

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .locale('en-us')
    .includeCount()
    .removeParam('include_count')
    .find();
  // No count key, because removeParam deleted the flag before find().
  console.log(result.count, result.entries?.length);
} 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 entries the response leaves out before the first one it returns.

Returns: Entries. The same query, for chaining.

Validation

• There is no client-side validation. The SDK sends zero, a negative number, or a fraction as given.
• 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 it.
• Combine skip with the limit method to read one page at a time. For page n of size s, pass skip(n * s) and limit(s), counting pages from 0.
• Calling it twice replaces the first value. The paginate method also writes skip, so whichever runs last sets the value.
• Known issue: In 5.x, includeReference, query, and the other Entries methods do not compile after skip, because TypeScript types the return value as Query. Call the Entries methods before skip, as Chain order on the Entry class page describes.

Example

Basic usage: skip the first twenty entries

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry().skip(20).find();
  console.log(result.entries?.length);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

Pagination: read every page of entries

import contentstack from '@contentstack/delivery-sdk';

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

try {
  const pageSize = 25;
  let page = 0;
  let total = 0;
  do {
    const result = await stack
      .contentType('<CONTENT_TYPE_UID>')
      .entry()
      .skip(page * pageSize)
      .limit(pageSize)
      .includeCount()
      .find();
    total = result.count ?? 0;
    console.log('page', page, 'entries', result.entries?.length);
    page += 1;
  } while (page * pageSize < total);
} catch (error: any) {
  console.error(error);
}

variants requests one or more variants of an entry instead of the base entry.

Returns: Entry or Entries. The same object, for chaining.

Validation

• There is no error for an empty value. An empty string or an empty array leaves any earlier variant UIDs in place. An empty or missing branchName leaves any earlier branch name in place. Neither case logs a message.
• variants does not check that a variant UID exists. The API returns the base entry for an unknown variant UID, with no error.
• A variant's display name does not work in place of its UID.
• Errors surface on the fetch() or find() call that follows, not on variants(). Those calls throw 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. variants stores the values and makes no request. The fetch() or find() call that follows sends them as request headers.
  • x-cs-variant-uid carries the variant UIDs. The SDK joins an array into one comma-separated string.
  • branch carries branchName, and replaces the stack-level branch header for that request.
• The Content Delivery API documentation states that the API accepts a variant alias in place of a variant UID. Aliases come from Contentstack Personalize.
• The API applies up to five variant UIDs or aliases per request by default. To raise the limit, email Contentstack support.
• The first variant in the list takes priority and applies to the base entry fields. For example, with ['red', 'green'], the red variant wins where both change a field.
• Above the limit, the request still succeeds, and the API applies only as many variants as the limit allows. Pass show_errors: 'true' through the addParams method to get an errors array with the code VARIANT_LIMIT_EXCEEDED. On fetch(), the SDK returns only the entry object, so the errors array reaches you only on find().
• A second call replaces the stored variant UIDs. It replaces the branch name only when you pass a new non-empty one.
• variants works the same way on Entry and Entries. On find(), the API applies the variants to every entry in the list.
• On Entries, call variants before the query method. The Query copies the variant UIDs and branch name when query() runs, so a later variants call on the Entries does not reach that query.

Example

Basic usage: read one variant of an entry

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

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .variants('<VARIANT_UID>')
    .fetch<BaseEntry>();
  console.log(result.title);
} catch (error: any) {
  // Thrown for API rejections and network failures
  console.error('Request failed:', error.status, error.error_code, error.error_message);
}

All parameters: pass the variant UIDs as an array and name a branch

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

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

try {
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry('<ENTRY_UID>')
    .variants(['<VARIANT_UID>'], 'main')
    .fetch<BaseEntry>();
  console.log(result.title);
} catch (error: any) {
  console.error(error);
}

List form: set the variant before opening a query

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

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

try {
  // variants() must run before query(), because the query copies the value.
  const result = await stack
    .contentType('<CONTENT_TYPE_UID>')
    .entry()
    .variants('<VARIANT_UID>')
    .query()
    .where('title', QueryOperation.EXISTS, true)
    .find();
  console.log(result.entries?.length);
} catch (error: any) {
  console.error(error);
}