Entry
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
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Export an entry | No | Read it with fetch |
| Unlocalize an entry or name an entry version | No | The SDK has no method for these requests |
| Publish an entry with its references in one call | No | Use the bulk publish of the BulkOperation class |
| Import from a file in a browser | No | import 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 Name | Returns | Description |
|---|---|---|
| query | A query for entries, sent when you call find(), findOne() or count(). | Builds an entry query. |
| create | The new entry. | Creates an entry. |
Read and change one entry. Available on stack.contentType('<CONTENT_TYPE_UID>').entry('<ENTRY_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested entry. | Retrieves one entry. |
| update | The updated entry. | Saves the fields of this object. |
| delete | The API response with a notice. | Deletes the entry or its localized versions. |
| locales | The API response with the languages of the entry. | Lists the languages of the entry. |
| references | The 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 Name | Returns | Description |
|---|---|---|
| publish | The API response with a notice. | Publishes the entry to environments. |
| unpublish | The API response with a notice. | Unpublishes the entry from environments. |
| publishRequest | The API response with a notice. | Requests, accepts or rejects publishing. |
| setWorkflowStage | The 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 Name | Returns | Description |
|---|---|---|
| variants | A new entry variant object. | Opens the variants of the entry. |
| includeVariants | The 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 Name | Returns | Description |
|---|---|---|
| import | The imported entry. | Imports an entry from a JSON file. |
| addHeader | The same entry, for chaining. | Adds one request header. |
| addHeaderDict | The same entry, for chaining. | Adds several request headers. |
| removeHeader | The 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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
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.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
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.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Request body with the field values under entry. |
| data.entry.title (required) | string | Title of the entry. |
| data.entry.url | string | URL of the entry, for page content types. |
| param | object | Query parameters, sent as given. |
| param.locale | string | Locale to create the entry in. |
| param.include_branch | boolean | Adds the _branch key to the response. |
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.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.locale | string | Locale of the version to delete. |
| param.delete_all_localized | boolean | Deletes every localized version of the entry too. |
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>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.version | number | Version of the entry to read. |
| param.locale | string | Locale to read the entry in. |
| param.include_workflow | boolean | Adds the workflow details of the entry. |
| param.include_publish_details | boolean | Adds the publish details of the entry. |
| param.include_branch | boolean | Adds the _branch key to the response. |
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.
| Name | Type | Description |
|---|---|---|
| options (required) | object | Holds the file path and the import settings. |
| options.entry (required) | string | Path of the entry JSON file. |
| options.locale | string | Locale to import the entry in. |
| options.overwrite | boolean | Replaces an existing entry with the file. |
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.
| Name | Type | Description |
|---|---|---|
| include_variant | boolean | string | Value of the include_variant query parameter. |
| variants_uid | string | Variant UID for the x-cs-variant-uid header. |
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.
| Name | Type | Description |
|---|---|---|
| options (required) | PublishConfig | Settings for the publish request. |
| options.publishDetails (required) | PublishDetails | Body content under the entry key. |
| options.publishDetails.environments (required) | string[] | Names of the environments to publish to. |
| options.publishDetails.locales | string[] | Codes of the locales to publish. |
| options.locale | string | Locale of the entry version to publish. |
| options.version | number | Version number of the entry to publish. |
| options.scheduledAt | string | Date and time in ISO 8601 format to publish at. |
| options.headers | object | Extra headers for this request only. |
| options.params | object | Query parameters for this request only. |
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.
| Name | Type | Description |
|---|---|---|
| options (required) | object | Holds the publish rule details and the locale. |
| options.publishing_rule (required) | object | Body content under workflow.publishing_rule. |
| options.publishing_rule.uid (required) | string | UID of the publish rule. |
| options.publishing_rule.action (required) | string | publish, unpublish or both. |
| options.publishing_rule.status (required) | number | 0 requests, 1 accepts, -1 rejects approval. |
| options.publishing_rule.notify | boolean | Notifies the approver. |
| options.publishing_rule.comment | string | Comment for the approver. |
| options.locale | string | Locale of the entry. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the request. |
| params.query | object | Condition on entry fields, sent as JSON. |
| params.locale | string | Locale to read the entries in. |
| params.include_workflow | boolean | Adds the workflow details of each entry. |
| params.include_publish_details | boolean | Adds the publish details of each entry. |
| params.apply_draft | boolean | Merges the draft of each entry into it. |
| params.include_count | boolean | Adds the total number of matching entries. |
| params.include_branch | boolean | Adds the _branch key to each entry. |
| params.limit | number | Maximum number of entries to return. |
| params.skip | number | Number of entries to skip. |
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.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.locale | string | Locale of the entry. |
| param.include_publish_details | boolean | Adds publish details of each referencing entry. |
| param.include_branch | boolean | Adds the _branch key to the response. |
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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
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.
| Name | Type | Description |
|---|---|---|
| options (required) | object | Holds the stage details and the locale. |
| options.workflow_stage (required) | WorkflowStage | Body content under workflow.workflow_stage. |
| options.workflow_stage.uid (required) | string | UID of the workflow stage. |
| options.workflow_stage.comment | string | Comment for the assigned users. |
| options.workflow_stage.due_date | string | Due date of the stage. |
| options.workflow_stage.notify | boolean | Notifies the assigned users. |
| options.workflow_stage.assigned_to | object[] | Users to assign, each with uid, name and email. |
| options.workflow_stage.assigned_by_roles | object[] | Roles to assign, each with uid and name. |
| options.locale | string | Locale of the entry. |
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.
| Name | Type | Description |
|---|---|---|
| options (required) | PublishConfig | Settings for the unpublish request. |
| options.publishDetails (required) | PublishDetails | Body content under the entry key. |
| options.publishDetails.environments (required) | string[] | Names of the environments to unpublish from. |
| options.publishDetails.locales | string[] | Codes of the locales to unpublish. |
| options.locale | string | Locale of the entry version to unpublish. |
| options.version | number | Version number of the entry to unpublish. |
| options.scheduledAt | string | Date and time in ISO 8601 format to unpublish at. |
| options.headers | object | Extra headers for this request only. |
| options.params | object | Query parameters for this request only. |
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.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.locale | string | Locale to save the entry in. |
| param.include_branch | boolean | Adds the _branch key to the response. |
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.
| Name | Type | Description |
|---|---|---|
| variantUidOrUids | string | string[] | UID of one variant, or several UIDs. |
| branchName | string | Branch UID or alias for this object only. |
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)
}