Entry

View as Markdown

Entry

An entry is one piece of content that follows the fields of a content type, such as one blog post. The Entry class manages the entries of one content type through the Content Management API (CMA). Use this class to

  • list, create and import the entries of a content type
  • read, update, localize and delete one entry
  • publish and unpublish an entry, and move it through a workflow
  • read the languages and references of an entry, and work with its variants

Call the entry method of a ContentType object that has a UID to get an object, for example stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').

Instance State

  • Call entry() without a UID to work with the entries of the content type, for example create and query.
  • Call entry('<ENTRY_UID>') to work with one entry, for example fetch and publish.
  • Each form has only its own methods, except import, which both forms have. fetch is undefined on entry(), and create is undefined on entry('<ENTRY_UID>'), so calling the wrong one throws TypeError.
  • The objects that fetch, create, update and query().find() return are the single-entry form.

Warning entry('') returns the collection form, because the SDK treats an empty string as no UID. Check the UID before you build the object.

Class-Level Notes

Branch scoping.

  • When you create the stack with branch_uid, every request from this class sends the branch header, and the API works with the entries of that branch.

Headers.

  • Every request sends the headers of this object, which start as the headers of the content type object. Change them for this entry only with addHeader, addHeaderDict and removeHeader.
  • The api_version header turns on nested reference publishing in the API. publish and unpublish also take headers for one request.

Locales.

  • Methods that read or change one language version of an entry take the locale code as a locale query parameter or option. Without it, the API works with the master locale.

Rate limiting and retry.

  • This SDK automatically retries on 429 with configurable delay and attempt limits.

Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.

Capability Matrix

CapabilitySupportedNotes / Alternative
Export an entryNoRead it with fetch
Unlocalize an entry or name an entry versionNoThe SDK has no method for these requests
Publish an entry with its references in one callNoUse the bulk publish of the BulkOperation class
Import from a file in a browserNoimport reads a file path with Node.js fs. Use create instead

Method Index

Work with the entries of a content type. Available on stack.contentType('<CONTENT_TYPE_UID>').entry(). The import method is in the last group.

Method NameReturnsDescription
queryA query for entries, sent when you call find(), findOne() or count().Builds an entry query.
createThe new entry.Creates an entry.

Read and change one entry. Available on stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').

Method NameReturnsDescription
fetchThe requested entry.Retrieves one entry.
updateThe updated entry.Saves the fields of this object.
deleteThe API response with a notice.Deletes the entry or its localized versions.
localesThe API response with the languages of the entry.Lists the languages of the entry.
referencesThe API response with the entries that reference this entry.Lists the referencing entries.

Publish and run workflows. Available on stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').

Method NameReturnsDescription
publishThe API response with a notice.Publishes the entry to environments.
unpublishThe API response with a notice.Unpublishes the entry from environments.
publishRequestThe API response with a notice.Requests, accepts or rejects publishing.
setWorkflowStageThe API response with a notice.Moves the entry to a workflow stage.

Work with entry variants. Available on stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').

Method NameReturnsDescription
variantsA new entry variant object.Opens the variants of the entry.
includeVariantsThe API response with the entry and the requested variant.Reads the entry with the fields of one variant.

Import and set request headers. Available on both forms.

Method NameReturnsDescription
importThe imported entry.Imports an entry from a JSON file.
addHeaderThe same entry, for chaining.Adds one request header.
addHeaderDictThe same entry, for chaining.Adds several request headers.
removeHeaderThe same entry, for chaining.Removes one request header.

Class-Level Snippet

The snippet below creates an entry, publishes it to one environment, and reads it back with its publish details.

import contentstack from '@contentstack/management'

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

try {
  const created = await contentType.entry().create({
    entry: { title: 'docs-test-blog-post', url: '/docs-test-blog-post' }
  })

  const published = await created.publish({
    publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'] }
  })
  console.log(published.notice)

  const entry = await contentType.entry(created.uid).fetch({ include_publish_details: true })
  console.log(entry.publish_details)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

Methods

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

addHeader

addHeader adds one header to every request that this entry object sends.

NameTypeDescription
key (required)string

Header name, for example x-request-id.

Default: Not applicable
value (required)string

Header value to send.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeader sends no request.
  • The first header change on this object copies the headers that it inherited from the stack. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
  • Every request method of this object sends its headers. A key that the object already holds gets the new value.
  • variants and query pass the headers of this object on to the objects they return. Change the headers first, then call them.
  • addHeader('api_version', '3.2') sends the header from this entry only. It is the safe alternative to the api_version option of entry.

Example

Basic usage: tag the requests of one entry object

import contentstack from '@contentstack/management'

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

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

addHeaderDict

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

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeaderDict sends no request.
  • Copies every key of headerDict into the headers of this object. A key that the object already holds gets the new value.
  • The first header change on this object copies the headers that it inherited from the stack. The change then applies to this object only.

Example

Basic usage: send two extra headers from one entry object

import contentstack from '@contentstack/management'

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

const entry = stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>')
  .addHeaderDict({ 'x-request-id': 'docs-123', api_version: '3.2' })
// publish() and unpublish() on this object send both headers
console.log(entry.stackHeaders)

create

create creates an entry in the content type from the field values you pass.

NameTypeDescription
data (required)object

Request body with the field values under entry.

Default: Not applicable
data.entry.title (required)string

Title of the entry.

Default: Not applicable
data.entry.urlstring

URL of the entry, for page content types.

Default: API default
paramobject

Query parameters, sent as given.

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

Locale to create the entry in.

Default: API default (master locale)
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Entry>. The new entry.

Validation

  • There is no client-side validation. create sends data as the JSON body as it is.
  • create exists only on entry(). On entry('<ENTRY_UID>') it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends POST /v3/content_types/{content_type_uid}/entries with data as the body, as Create an entry describes.
  • Every field of the content type goes under data.entry with its field UID as the key. Pass an asset field as the asset UID, and a reference field as an array of { uid, _content_type_uid } objects.
  • Resolves to a new Entry object that holds the fields of the created entry, with fetch, update, publish and delete.

Example

Basic usage: create a blog post

import contentstack from '@contentstack/management'

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

try {
  const entry = await stack.contentType('<CONTENT_TYPE_UID>').entry().create({
    entry: { title: 'docs-test-blog-post', url: '/docs-test-blog-post' }
  })
  console.log(entry.uid)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: create a French entry with an asset and a reference on a branch

import contentstack from '@contentstack/management'

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

const entry = {
  title: 'docs-test-article',
  url: '/docs-test-article',
  banner: '<ASSET_UID>',
  author: [{ uid: '<ENTRY_UID>', _content_type_uid: 'author' }]
}

try {
  const created = await stack.contentType('<CONTENT_TYPE_UID>').entry()
    .create({ entry }, { locale: 'fr-fr', include_branch: true })
  console.log(created.uid, created.locale, created._branch)
} catch (error) {
  console.error(error.errorMessage)
}

delete

delete removes the entry whose UID you passed to entry('<ENTRY_UID>'), or some of its localized versions.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.localestring

Locale of the version to delete.

Default: API default (master locale)
param.delete_all_localizedboolean

Deletes every localized version of the entry too.

Default: API default

Returns: Promise<Response>. The API response with a notice.

Warning A successful delete removes the entry, or the localized version you name, and you cannot undo it.

Validation

  • There is no client-side validation.
  • delete exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends DELETE /v3/content_types/{content_type_uid}/entries/{entry_uid} with every key of param as a query parameter, as Delete an entry describes.
  • Without locale, the API deletes the master locale entry. With locale, it deletes that localized version only.
  • Resolves to the response body, which carries notice. When the API answers with an empty body, it resolves to { status, statusText } instead.

Example

Basic usage: delete an entry

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').delete()
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: delete the entry with all its localized versions

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>')
    .delete({ locale: '<LOCALE>', delete_all_localized: true })
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

fetch

fetch retrieves the entry whose UID you passed to entry('<ENTRY_UID>').

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.versionnumber

Version of the entry to read.

Default: API default (latest version)
param.localestring

Locale to read the entry in.

Default: API default (master locale)
param.include_workflowboolean

Adds the workflow details of the entry.

Default: API default
param.include_publish_detailsboolean

Adds the publish details of the entry.

Default: API default
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Entry>. The requested entry.

Validation

  • There is no client-side validation.
  • fetch exists only on entry('<ENTRY_UID>') and on the objects that create, update and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends GET /v3/content_types/{content_type_uid}/entries/{entry_uid} with every key of param as a query parameter, as Get a single entry describes.
  • To read a specific version, send no environment parameter, as the API reference states.
  • Resolves to a new Entry object that holds the entry fields, with update, delete, publish and the other single-entry methods. The object you called fetch on does not change.
  • The SDK copies the content_type and schema keys of the response, when present, onto the returned entry.

Example

Basic usage: read one entry

import contentstack from '@contentstack/management'

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

try {
  const entry = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').fetch()
  console.log(entry.title, entry._version)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: read version 2 of the French entry with workflow and publish details

import contentstack from '@contentstack/management'

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

try {
  const entry = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').fetch({
    version: 2,
    locale: 'fr-fr',
    include_workflow: true,
    include_publish_details: true,
    include_branch: true
  })
  console.log(entry._version, entry.publish_details, entry._workflow, entry._branch)
} catch (error) {
  console.error(error.errorMessage)
}

import

import creates an entry from a JSON file, or, on entry('<ENTRY_UID>'), adds a new version of that entry from the file.

NameTypeDescription
options (required)object

Holds the file path and the import settings.

Default: Not applicable
options.entry (required)string

Path of the entry JSON file.

Default: Not applicable
options.localestring

Locale to import the entry in.

Default: null (not sent)
options.overwriteboolean

Replaces an existing entry with the file.

Default: false

Returns: Promise<Entry>. The imported entry.

Known issue The Entry object that import returns has no content type UID, so its own methods send requests to /content_types/undefined/... and fail. Call stack.contentType('<CONTENT_TYPE_UID>').entry(imported.uid) to work with the imported entry.

Validation

  • There is no client-side validation. The SDK does not check that the file exists before it sends the request.
  • Without options, the returned promise rejects with a TypeError, because the SDK reads its properties before it sends anything.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • On entry(), sends POST /v3/content_types/{content_type_uid}/entries/import, as Import an entry describes.
  • On entry('<ENTRY_UID>'), sends POST /v3/content_types/{content_type_uid}/entries/{entry_uid}/import, as Import an existing entry describes. The API adds the file as a new version of the entry.
  • Sends the file as multipart/form-data in a field named entry. Always sends overwrite, and sends locale only when you pass it.
  • Reads the file with the Node.js fs module, so import runs only in Node.js.

Example

Basic usage: import an entry from a file

import contentstack from '@contentstack/management'

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

try {
  const imported = await contentType.entry().import({ entry: '<FILE_PATH>' })
  // Rebuild the entry object from the content type before you call its methods
  const entry = await contentType.entry(imported.uid).fetch()
  console.log(entry.uid, entry.title)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: import a new French version of an existing entry

import contentstack from '@contentstack/management'

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

try {
  const imported = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>')
    .import({ entry: '<FILE_PATH>', locale: 'fr-fr', overwrite: true })
  console.log(imported.uid, imported.locale)
} catch (error) {
  console.error(error.errorMessage)
}

includeVariants

includeVariants reads the entry with the fields of one variant, which it names in the x-cs-variant-uid header. The following table lists its parameters.

NameTypeDescription
include_variantboolean | string

Value of the include_variant query parameter.

Default: undefined (not sent)
variants_uidstring

Variant UID for the x-cs-variant-uid header.

Default: undefined (header not sent)

Returns: Promise<Response>. The API response with the entry and the requested variant.

Validation

  • There is no client-side validation.
  • includeVariants exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends GET /v3/content_types/{content_type_uid}/entries/{entry_uid}, the Get a single entry request, with the x-cs-variant-uid header set to variants_uid.
  • Sends include_variant as a query parameter only when its value is truthy. false and '' send nothing.
  • Resolves to the response body as the API returns it, not to an Entry object. The entry is under entry.
  • To read, change or publish one variant, use the variants method.

Example

Basic usage: read an entry with one variant applied

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>')
    .includeVariants(true, '<VARIANT_UID>')
  console.log(response.entry.title)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

locales

locales lists the languages that the entry exists in.

This method takes no parameters.

Returns: Promise<Response>. The API response with the languages of the entry.

Validation

  • There is no client-side validation.
  • locales exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends GET /v3/content_types/{content_type_uid}/entries/{entry_uid}/locales, as Get languages of an entry describes. It sends no query parameters.
  • Resolves to the response body as the API returns it. The TypeScript declarations of the SDK describe it as { locales: [{ code, localized }] }.

Example

Basic usage: list the languages of an entry

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').locales()
  for (const locale of response.locales) {
    console.log(locale.code, locale.localized)
  }
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

publish

publish publishes the entry to the environments and locales you name, at once or at a scheduled time.

NameTypeDescription
options (required)PublishConfig

Settings for the publish request.

Default: Not applicable
options.publishDetails (required)PublishDetails

Body content under the entry key.

Default: Not applicable
options.publishDetails.environments (required)string[]

Names of the environments to publish to.

Default: Not applicable
options.publishDetails.localesstring[]

Codes of the locales to publish.

Default: API default (master locale)
options.localestring

Locale of the entry version to publish.

Default: null (not sent)
options.versionnumber

Version number of the entry to publish.

Default: null (not sent)
options.scheduledAtstring

Date and time in ISO 8601 format to publish at.

Default: null (not sent)
options.headersobject

Extra headers for this request only.

Default: {}
options.paramsobject

Query parameters for this request only.

Default: {}

Returns: Promise<Response>. The API response with a notice.

Validation

  • There is no client-side validation.
  • publish exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • Without options, the returned promise rejects with a TypeError, because the SDK reads its properties before it sends anything.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends POST /v3/content_types/{content_type_uid}/entries/{entry_uid}/publish, as Publish an entry describes. The body is { entry: publishDetails, locale, version, scheduled_at }, and the SDK leaves out each of the last three that is null.
  • Sends the headers of this object merged with options.headers, and options.params as query parameters.
  • Without scheduledAt, the API publishes at once. The API also publishes the metadata of the entry.
  • The API reference lists the api_version header for nested reference publishing. publish adds no api_version header. Pass it in options.headers, or call addHeader on the entry.
  • Resolves to the response body, which carries notice. The SDK adds a stackHeaders key to it, with the headers of this object.
  • To publish one entry variant, see the publish method of EntryVariant.

Example

Basic usage: publish an entry to one environment

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').publish({
    publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'] }
  })
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: schedule version 2 with nested reference publishing

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').publish({
    publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['en-us', 'fr-fr'] },
    locale: 'en-us',
    version: 2,
    scheduledAt: '2026-12-01T09:00:00.000Z',
    headers: { api_version: '3.2' },
    params: { include_branch: true }
  })
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

publishRequest

publishRequest sends a publish request for the entry, or accepts or rejects a publish request that the entry received. The following table lists its parameters.

NameTypeDescription
options (required)object

Holds the publish rule details and the locale.

Default: Not applicable
options.publishing_rule (required)object

Body content under workflow.publishing_rule.

Default: Not applicable
options.publishing_rule.uid (required)string

UID of the publish rule.

Default: Not applicable
options.publishing_rule.action (required)string

publish, unpublish or both.

Default: Not applicable
options.publishing_rule.status (required)number

0 requests, 1 accepts, -1 rejects approval.

Default: Not applicable
options.publishing_rule.notifyboolean

Notifies the approver.

Default: API default
options.publishing_rule.commentstring

Comment for the approver.

Default: API default
options.localestring

Locale of the entry.

Default: undefined (not sent)

Returns: Promise<Response>. The API response with a notice.

Validation

  • There is no client-side validation.
  • publishRequest exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • Without options, the returned promise rejects with a TypeError, because the SDK reads its properties before it sends anything.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends POST /v3/content_types/{content_type_uid}/entries/{entry_uid}/workflow?locale={locale} with the body { workflow: { publishing_rule } }, as Request/Accept/Reject Entry Publish Request describes.
  • The API reference lists the authtoken header for this request. Use a client created with an authtoken, as in the examples below.
  • Resolves to the response body as the API returns it.

Example

Basic usage: request approval to publish an entry

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').publishRequest({
    publishing_rule: { uid: '<PUBLISH_RULE_UID>', action: 'publish', status: 0 },
    locale: '<LOCALE>'
  })
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: accept a publish request and notify the requester

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').publishRequest({
    publishing_rule: {
      uid: '<PUBLISH_RULE_UID>',
      action: 'publish',
      status: 1,
      notify: true,
      comment: 'Approved for the launch.'
    },
    locale: '<LOCALE>'
  })
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

query

query builds a request for the entries of the content type. It sends nothing until you call a method of the returned query.

NameTypeDescription
paramsobject

Query parameters for the request.

Default: {}
params.queryobject

Condition on entry fields, sent as JSON.

Default: API default
params.localestring

Locale to read the entries in.

Default: API default (master locale)
params.include_workflowboolean

Adds the workflow details of each entry.

Default: API default
params.include_publish_detailsboolean

Adds the publish details of each entry.

Default: API default
params.apply_draftboolean

Merges the draft of each entry into it.

Default: API default
params.include_countboolean

Adds the total number of matching entries.

Default: API default
params.include_branchboolean

Adds the _branch key to each entry.

Default: API default
params.limitnumber

Maximum number of entries to return.

Default: API default
params.skipnumber

Number of entries to skip.

Default: API default

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

Validation

  • There is no client-side validation.
  • query exists only on entry(). On entry('<ENTRY_UID>') it is undefined, and calling it throws TypeError.
  • An invalid value surfaces as a rejected promise from the request method you call next.

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

Behavior

  • Client-side only. query copies the headers of this object and params, and returns a Query object.
  • find and findOne send GET /v3/content_types/{content_type_uid}/entries and resolve to Entry objects, as Get all entries describes. count resolves to the response body.
  • Each Entry in items knows its content type, so its fetch, update and publish work without another lookup.
  • The SDK sends params.query as query=<JSON>, and every other key of params as a query parameter.

Example

Basic usage: list entries by title

import contentstack from '@contentstack/management'

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry()
    .query({ query: { title: 'Hello' } })
    .find()
  for (const entry of result.items) {
    console.log(entry.uid, entry.title)
  }
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: read the second page of French entries with workflow and publish details

import contentstack from '@contentstack/management'

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

try {
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry()
    .query({
      query: { title: { $regex: '^Hello' } },
      locale: 'fr-fr',
      include_workflow: true,
      include_publish_details: true,
      apply_draft: true,
      include_count: true,
      include_branch: true,
      limit: 10,
      skip: 10
    })
    .find()
  console.log(result.count)
  for (const entry of result.items) {
    console.log(entry.uid, entry.publish_details, entry._workflow)
  }
} catch (error) {
  console.error(error.errorMessage)
}

references

references lists the entries and content types that reference this entry. The following table lists its parameters.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.localestring

Locale of the entry.

Default: API default (master locale)
param.include_publish_detailsboolean

Adds publish details of each referencing entry.

Default: API default
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Response>. The API response with the entries that reference this entry.

Validation

  • There is no client-side validation.
  • references exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends GET /v3/content_types/{content_type_uid}/entries/{entry_uid}/references with every key of param as a query parameter, as Get references of an entry describes.
  • Resolves to the response body as the API returns it. The TypeScript declarations of the SDK describe it as { references: [...] }, each item with entry_uid, content_type_uid, locale and title.

Example

Basic usage: list the entries that reference an entry

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').references()
  for (const reference of response.references) {
    console.log(reference.content_type_uid, reference.entry_uid)
  }
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: list French references with publish details

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>')
    .references({ locale: 'fr-fr', include_publish_details: true, include_branch: true })
  console.log(JSON.stringify(response.references, null, 2))
} catch (error) {
  console.error(error.errorMessage)
}

removeHeader

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

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: Entry. The same entry, for chaining.

Validation

  • There is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. removeHeader sends no request.
  • Removing a header that the object inherited from the stack first copies the inherited headers, so the stack and other objects keep the header.
  • The SDK adds some headers at request time, for example the authorization header of the client. removeHeader cannot remove those.

Example

Basic usage: send requests from one entry object without the branch header

import contentstack from '@contentstack/management'

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

const entry = stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').removeHeader('branch')
// This object now works with the default branch
console.log(entry.stackHeaders.branch)

setWorkflowStage

setWorkflowStage moves the entry to a workflow stage, or changes the stage details of the entry. The following table lists its parameters.

NameTypeDescription
options (required)object

Holds the stage details and the locale.

Default: Not applicable
options.workflow_stage (required)WorkflowStage

Body content under workflow.workflow_stage.

Default: Not applicable
options.workflow_stage.uid (required)string

UID of the workflow stage.

Default: Not applicable
options.workflow_stage.commentstring

Comment for the assigned users.

Default: API default
options.workflow_stage.due_datestring

Due date of the stage.

Default: API default
options.workflow_stage.notifyboolean

Notifies the assigned users.

Default: API default
options.workflow_stage.assigned_toobject[]

Users to assign, each with uid, name and email.

Default: API default
options.workflow_stage.assigned_by_rolesobject[]

Roles to assign, each with uid and name.

Default: API default
options.localestring

Locale of the entry.

Default: undefined (not sent)

Returns: Promise<Response>. The API response with a notice.

Validation

  • There is no client-side validation.
  • setWorkflowStage exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • Without options, the returned promise rejects with a TypeError, because the SDK reads its properties before it sends anything.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends POST /v3/content_types/{content_type_uid}/entries/{entry_uid}/workflow?locale={locale} with the body { workflow: { workflow_stage } }, as Set entry workflow stage describes.
  • The API reference lists the authtoken header for this request. Use a client created with an authtoken, as in the examples below.
  • Resolves to the response body as the API returns it.

Example

Basic usage: move an entry to a workflow stage

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').setWorkflowStage({
    workflow_stage: { uid: '<WORKFLOW_STAGE_UID>', comment: 'Ready for review' },
    locale: '<LOCALE>'
  })
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: assign a stage to a user and a role with a due date

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').setWorkflowStage({
    workflow_stage: {
      uid: '<WORKFLOW_STAGE_UID>',
      comment: 'Review the French copy',
      due_date: 'Thu Dec 10 2026',
      notify: true,
      assigned_to: [{ uid: '<USER_UID>', name: 'Jane Doe', email: '<COLLABORATOR_EMAIL>' }],
      assigned_by_roles: [{ uid: '<ROLE_UID>', name: 'Reviewer' }]
    },
    locale: '<LOCALE>'
  })
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

unpublish

unpublish unpublishes the entry from the environments and locales you name, at once or at a scheduled time.

NameTypeDescription
options (required)PublishConfig

Settings for the unpublish request.

Default: Not applicable
options.publishDetails (required)PublishDetails

Body content under the entry key.

Default: Not applicable
options.publishDetails.environments (required)string[]

Names of the environments to unpublish from.

Default: Not applicable
options.publishDetails.localesstring[]

Codes of the locales to unpublish.

Default: API default (master locale)
options.localestring

Locale of the entry version to unpublish.

Default: null (not sent)
options.versionnumber

Version number of the entry to unpublish.

Default: null (not sent)
options.scheduledAtstring

Date and time in ISO 8601 format to unpublish at.

Default: null (not sent)
options.headersobject

Extra headers for this request only.

Default: {}
options.paramsobject

Query parameters for this request only.

Default: {}

Returns: Promise<Response>. The API response with a notice.

Warning A successful unpublish removes the entry from the delivery of the environments you name. The entry stays in the stack, and you can publish it again with publish.

Validation

  • There is no client-side validation.
  • unpublish exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • Without options, the returned promise rejects with a TypeError, because the SDK reads its properties before it sends anything.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends POST /v3/content_types/{content_type_uid}/entries/{entry_uid}/unpublish, as Unpublish an entry describes. The body is { entry: publishDetails, locale, version, scheduled_at }, and the SDK leaves out each of the last three that is null.
  • Sends the headers of this object merged with options.headers, and options.params as query parameters.
  • Without publishDetails.locales, the API unpublishes the entry from the master locale. Without scheduledAt, it unpublishes at once.
  • The API reference lists the api_version header for nested reference publishing. unpublish adds no api_version header. Pass it in options.headers.
  • Resolves to the response body, which carries notice. The SDK adds a stackHeaders key to it, with the headers of this object.

Example

Basic usage: unpublish an entry from one environment

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').unpublish({
    publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'] }
  })
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: schedule an unpublish of version 2

import contentstack from '@contentstack/management'

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

try {
  const response = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').unpublish({
    publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['en-us'] },
    locale: 'en-us',
    version: 2,
    scheduledAt: '2026-12-31T23:00:00.000Z',
    headers: { api_version: '3.2' },
    params: { include_branch: true }
  })
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

update

update saves the field values that this entry object holds to the stack, or localizes the entry when you pass a locale.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.localestring

Locale to save the entry in.

Default: API default (master locale)
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Entry>. The updated entry.

Validation

  • There is no client-side validation.
  • update exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

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

Behavior

  • Sends PUT /v3/content_types/{content_type_uid}/entries/{entry_uid} with the body { entry: <fields of this object> }, as Update an entry describes. The SDK leaves out uid, created_at, created_by, updated_at, updated_by and its own keys.
  • Before it sends the body, the SDK replaces each asset object, an object with uid and file_size or content_type, with its asset UID.
  • The body holds only the fields this object has. Call fetch first, change the fields of the object it returns, and then call update.
  • With param.locale, the API localizes the entry in that locale, as Update an entry states.
  • The API does not change the workflow stage on update. Use setWorkflowStage.
  • Resolves to a new Entry object with the saved fields.

Example

Basic usage: change the title of an entry

import contentstack from '@contentstack/management'

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

try {
  const entry = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').fetch()
  entry.title = 'Hello again'
  const updated = await entry.update()
  console.log(updated.title, updated._version)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: localize an entry in French on a branch

import contentstack from '@contentstack/management'

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

try {
  const entry = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').fetch()
  entry.title = 'Bonjour'
  const localized = await entry.update({ locale: 'fr-fr', include_branch: true })
  console.log(localized.locale, localized._branch)
} catch (error) {
  console.error(error.errorMessage)
}

variants

variants returns an object for the variants of this entry, or for one variant when you pass its UID. It sends no request.

NameTypeDescription
variantUidOrUidsstring | string[]

UID of one variant, or several UIDs.

Default: undefined (returns the collection form)
branchNamestring

Branch UID or alias for this object only.

Default: undefined (uses the branch of the entry)

Returns: EntryVariant. A new entry variant object.

Validation

  • There is no client-side validation.
  • variants exists only on entry('<ENTRY_UID>') and on the objects that fetch, create and query().find() return. On entry() it is undefined, and calling it throws TypeError.
  • An invalid value surfaces as a rejected promise from the request method you call next.

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

Behavior

  • Client-side only. variants builds an EntryVariant object with the content type UID, the entry UID and the headers of this entry.
  • With one UID, the object works with one variant, for example fetch, update and publish.
  • With an array, the SDK drops empty strings and values that are not strings. One UID left works like a single UID, and the SDK joins several with commas into the request path.
  • Without a UID, the object works with all variants of the entry and has query only. An empty string, or an array with no UID left, gives the same object.
  • A non-empty branchName sets the branch header on the returned object only. The entry keeps its own headers.

Example

Basic usage: read one variant of an entry

import contentstack from '@contentstack/management'

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

try {
  const variant = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>')
    .variants('<VARIANT_UID>')
    .fetch()
  console.log(variant.entry.title)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: list the variants of an entry on a branch

import contentstack from '@contentstack/management'

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

try {
  // An empty array returns the collection form, which has query()
  const result = await stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>')
    .variants([], '<BRANCH>')
    .query()
    .find()
  for (const variant of result.items) {
    console.log(variant.variants_uid)
  }
} catch (error) {
  console.error(error.errorMessage)
}