Entry

An Entry is the actual piece of content created using one of the defined content types. To work with a single entry, specify its UID.

Example:

import contentstack from '@contentstack/delivery-sdk'

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



const stack = contentstack.stack({ apiKey: "apiKey", deliveryToken: "deliveryToken", environment: "environment" });

interface BlogPostEntry extends BaseEntry {

  // custom entry types

}

async function fetchEntry() {

    try {

const result = await stack.contentType(contenttype_uid).entry(entry_uid).fetch<BlogPostEntry>();

      console.log('Entry: ', result);

//Add your statements

    } catch (error) {

      console.error('Error fetching entry:', error);

  }

}

fetchEntry();

Name	Type	Description
entryUid	entryUid	UID of the entry

fetch

The fetch method retrieves the details of a specific entry.

Example:

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



interface BlogPostEntry extends BaseEntry {

  // custom entry types

}

const result = await stack

                      .contentType(contentType_uid)

                      .entry(entry_uid)

                      .fetch<BlogPostEntry>();

includeBranch

The includeBranch method includes the branch details in the result.

Example:

const result = await stack

                       .contentType(contentType_uid)

                       .entry(entry_uid)

                       .includeBranch()

                       .fetch<BlogPostEntry>();

includeFallback

The includeFallback method retrieves the entry in its fallback language.

Example:

const result = await stack

                       .contentType(contentType_uid)

                       .entry(entry_uid)

                       .includeFallback()

                       .fetch<BlogPostEntry>();

locale

The locale method retrieves the entries published in that locale.

Name	Type	Description
locale (required)	string	Locale of the entry

Example:

const result = await stack

                       .contentType(contentType_uid)

                       .entry(entry_uid)

                       .locale('en-us')

                       .fetch<BlogPostEntry>();

addParams

The addParam method adds a query parameter to the query.

Name	Type	Description
paramObj (required)	object	Add key-value pairs

Example:

import { BaseEntry, FindEntry } from '@contentstack/delivery-sdk'



interface BlogPostEntry extends BaseEntry {

  // custom entry types

}


const result = await stack

                       .contentType(contentType_uid)

                       .entry()

                       .addParams({"key": "value"})

                       .find<BlogPostEntry>();

except

The except method excludes specific field(s) of an entry.

Name	Type	Description
fieldUid (required)	string	UID of the field to exclude

Example:

const result = await stack

                       .contentType("contentTypeUid")

                       .entry()

                       .except("fieldUID")

                       .find<BlogPostEntry>();

find

The find method retrieves the details of the specified entry.

Example:

const result = await stack.contentType("contentTypeUid").entry().find<BlogPostEntry>();

skip

The skip method will skip a specific number of entries in the output.

Name	Type	Description
skipBy (required)	int	Enter the number of entries to be skipped.

Example:

const result = await stack

                       .contentType(contentType_uid)

                       .entry()

                       .skip(5)

                       .find<BlogEntry>();

limit

The limit method will return a specific number of entries in the output.

Name	Type	Description
limit (required)	int	Enter the maximum number of entries to be returned.

Example:

const result = await stack

                       .contentType(contentType_uid)

                       .entry()

                       .limit(5)

                       .find<BlogEntry>();

includeCount

The includeCount method retrieves the count and data of objects in the result.

Example:

const result = await stack

                       .contentType("contentTypeUid")

                       .entry()

                       .includeCount()

                       .find<BlogPostEntry>();

only

The only method selects specific field(s) of an entry.

Name	Type	Description
fieldUid (required)	string	UID of the field to select

Example:

const result = await stack

                       .contentType("contentTypeUid")

                       .entry()

                       .only("fieldUID")

                       .find<BlogPostEntry>();

orderByAscending

The orderByAscending sorts the results in ascending order based on the specified field UID.

Name	Type	Description
key (required)	string	Field UID to sort the results

Example:

const result = await stack

                       .contentType("contentTypeUid")

                       .entry()

                       .orderByAscending()

                       .find<BlogPostEntry>();

orderByDescending

The orderByDescending sorts the results in descending order based on the specified field UID.

Name	Type	Description
key (required)	string	Field UID to sort the results

Example:

const result = await stack

                       .contentType("contentTypeUid")

                       .entry()

                       .orderByDescending()

                       .find<BlogPostEntry>();

param

The param method adds query parameters to the URL.

Name	Type	Description
key (required)	string	Add any param to include in the response
value (required)	string \| number	Add the corresponding value of the param key

Example:

const result = await stack

                       .contentType("contentTypeUid")

                       .entry()

                       .param("key", "value")

                       .find<BlogPostEntry>();

query

The query method retrieves the details of the entry on the basis of the queries applied.

Name	Type	Description
queryObj	object	Query in object format

Example:

const query = stack.contentType("contentTypeUid").entry().query({ "price_in_usd": { "$lt": 600 }});
const result = await query.whereIn("brand").find<BlogPostEntry>();

removeParam

The removeParam method removes a query parameter from the query.

Name	Type	Description
key (required)	string	Specify the param key you want to remove

Example:

const result = await stack

                       .contentType("contentTypeUid")

                       .entry()

                       .removeParam("query_param_key")

                       .find<BlogPostEntry>();

where

The where method filters the results based on the specified criteria.

Name	Type	Description
fieldUid (required)	string	Specify the field the comparison is made from
queryOperation (required)	QueryOperationEnum	Specify the comparison criteria
fields (required)	string	Specify the field the comparison is made to

Example:

const result = await stack

                       .contentType(contentType_uid)

                       .entry()

                       .query()

                       .where(

                         "field_UID", 

                         QueryOperation.IS_LESS_THAN, 

                         ["field1", "field2"])

                       .find<BlogPostEntry>();

includeMetadata

The includeMetadata method includes the metadata for getting metadata content for the entry.

Example:

const result = await stack

                       .contentType('contentType_uid')

                       .entry('entry_uid')

                       .includeMetadata()

                       .fetch<BlogEntry>();

includeEmbeddedItems

The includeEmbeddedItems method includes embedded objects (Entry and Assets) along with entry details

Example:

const result = await stack

                       .contentType(contentType_uid)

                       .entry('entry_uid')

                       .includeEmbeddedItems()

                       .fetch<BlogEntry>();

includeContentType

The includeContentType method includes the details of the content type along with the Entry details.

Example:

const result = await stack

                       .contentType(contentType_uid)

                       .entry('entry_uid')

                       .includeContentType()

                       .fetch<BlogEntry>();

includeReference

The includeReference method retrieves the content of the referred entries in your response.

Name	Type	Description
referenceFieldUid (required)	string	UID of the reference field to include

Example:

const query = stack.contentType(contentType_uid).entry();
const result = await query
                      .includeReference("brand")
                      .find<BlogPostEntry>();

To retrieve all referred entries, use the following code snippet:

const result = await query.addParams({ include_all: true, include_all_depth: 2 }).find();

NoteThe maximum supported value for include_all_depth is 100.

Variants

Variants are different versions of content designed to meet specific needs or target audiences. This feature allows content editors to create multiple variations of a single entry, each customized for a particular variant group or purpose.

When Personalize creates a variant in the CMS, it assigns a "Variant Alias" to identify that specific variant. When fetching entry variants using the Delivery API, you can pass variant aliases in place of variant UIDs in the x-cs-variant-uid header.

Single Variant: This method retrieves the details of a specific entry variant.

Example:

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

const Stack = contentstack.stack
({'api_key': 'api_key', 'delivery_token': 'delivery_token', 'environment': 'environment'});
const result = await Stack
                    .contentType('content_type_uid')
                    .entry('entry_uid')
                    .variants('variant_uid/variant_alias')
                    .fetch();

Layering variants: This method retrieves the details of entry variants based on the applied query

Example:

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

const Stack = contentstack.stack
({'api_key': 'api_key', 'delivery_token': 'delivery_token', 'environment': 'environment'});
const result = await Stack
                      .contentType('content_type_uid')
                      .entry('entry_uid')
                      .variants(['variant_uid1/variant_alias1','variant_uid2/variant_alias2'])
                      .fetch();

NoteBy default you can add up to 3 variant UIDs or aliases. The limit can vary based on your organization plan. The variant UID or alias added first takes priority and will be applied to the base entry fields.

assetFields

The assetFields method specifies the optional asset field groups to include for assets returned with an entry.

Note The assetFields method is supported only in the North America (NA) region.

Response Behavior:

Retrieves only the required asset metadata, keeping the entry payloads smaller when entries reference assets.
Applies to published assets referenced or embedded on the entry. It applies to both single-entry and multi-entry responses.
Adds optional metadata fields to each asset in the response. It does not filter assets or control file types.
Requests optional metadata groups in addition to standard asset fields such as file MIME type (content_type) and folder flag (is_dir). It does not replace or modify core asset fields.

Note On asset objects, content_type represents the file’s MIME type, not a Contentstack CMS content type.

Supported field groups (values):

user_defined_fields: Includes stack-defined custom fields on the asset (author-managed key-value data).
embedded_metadata: Includes metadata extracted from the file (e.g, EXIF or IPTC).
ai_generated_metadata: Includes AI-generated data (e.g., tags, descriptions, classifications).
visual_markups: Includes annotation data (e.g., regions, notes, overlays)

Name	Type	Description
fieldGroups	string	Keys that specify asset field groups to retrieve for assets in the entry response. Provide them as arguments before .fetch() or .find(). Default: NA

Note The SDK forwards invalid or empty field group strings without validating them. The API handles the errors.

Usage and Behavior:

Chain on a single entry or on an entry query, for example:
stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').assetFields(...).fetch()
or
stack.contentType('<CONTENT_TYPE_UID>').entry().assetFields(...).find().
Multiple calls overwrite prior values. Calling with no arguments omits asset_fields[] from the request.

Examples:

The following example fetches a single BlogEntry. Nested assets include the optional metadata. Asset fields and structure depend on your content type.

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

interface HeroAsset extends BaseAsset {
  user_defined_fields?: {
    photographer?: string;
    license?: string;
  };
  ai_generated_metadata?: {
    tags?: string[];
    description?: string;
  };
  // Visual annotation / overlay payload shape is app-specific; use `unknown` until you define a narrow interface.
  visual_markups?: unknown;
  // Binary-embedded file metadata (e.g. EXIF-style); structure varies by file type. Type narrowly or validate at runtime.
  embedded_metadata?: unknown;
}

interface BlogEntry extends BaseEntry {
  // Replace `hero_image` with your file-field UID; linked asset shape matches your stack.
  hero_image?: HeroAsset;
}

async function main() {
  try {
    const stack = contentstack.stack({
      apiKey: '<API_KEY>',
      deliveryToken: '<DELIVERY_TOKEN>',
      environment: '<ENVIRONMENT>',
    });
    const entryResponse = await stack
      .contentType('<CONTENT_TYPE_UID>')
      .entry('<ENTRY_UID>')
      .assetFields(
        'user_defined_fields',
        'embedded_metadata',
        'ai_generated_metadata',
        'visual_markups'
      )
      // Generic tells TypeScript the resolved entry shape (including nested asset field groups above).
      .fetch<BlogEntry>();
    console.log(entryResponse);
  } catch (error) {
    console.error(error);
  }
}

This example runs an entry query with two asset field groups and reads results from entries on the find response.

import contentstack from '@contentstack/delivery-sdk';
async function main() {
  try {
    const stack = contentstack.stack({
      apiKey: '<API_KEY>',
      deliveryToken: '<DELIVERY_TOKEN>',
      environment: '<ENVIRONMENT>',
    });
    const result = await stack
      .contentType('<CONTENT_TYPE_UID>')
      .entry()
      .assetFields('ai_generated_metadata', 'visual_markups')
      .find();
    // Collection responses use `entries` on FindResponse (not `items`).
    console.log(result.entries);
  } catch (error) {
    console.error(error);
  }
}

Data Retrieval Behavior:

Typing dynamic responses: Optional blocks returned for assetFields on nested assets are not part of the SDK’s BaseAsset type and vary by stack and field. Extend and compose BaseAsset in types that match your entry’s file fields, pass the entry type to .fetch<MyEntry>() or .find<MyEntry>(), then validate or narrow the payload before use.
Pagination and execution: Terminal methods (.fetch(), .find()) trigger a single HTTP request. Control page size and offset using query modifiers (e.g., limit, skip), or the system falls back to API defaults.

Additional Resources For detailed API payload schemas and default behaviors, refer to Contentstack Delivery API Documentation.