BulkOperation

View as Markdown

BulkOperation

A bulk operation acts on many entries and assets in one request. Use the BulkOperation class to do the following tasks:

  • publish, unpublish or delete entries and assets in bulk
  • change the workflow stage of many entries at once
  • add items to a release, or update the items of a release, in bulk
  • read the status and the items of a bulk job

The bulkOperation method on Stack returns a new BulkOperation and sends no request. It takes no UID, so every method is available on the object.

Additional Resource The Bulk Operations and Job Status sections of the Content Management API (CMA) reference describe each request and its limits.

Class-Level Notes

Options objects.

How failures reach your code.

  • publish, unpublish, delete and update return a promise that rejects with an Error when the API rejects the request.
  • addItems, updateItems, jobStatus and getJobItems write the error to the console and resolve to undefined. Each of these method pages includes a Known issue line with the workaround.

Bulk limits. The API applies the following limits to bulk requests:

  • One bulk publish or unpublish request covers up to 10 entries, in up to 10 locales and 10 environments.
  • One bulk delete request covers up to 100 entries.
  • The default rate limit for bulk actions is one request per second, lower than the standard limit.

Jobs.

  • The API runs a bulk request as a background job. The promise resolves when the API accepts the request, not when the job finishes.
  • Read the progress of a job with jobStatus and its items with getJobItems.

Headers and branches.

  • stack.bulkOperation() gives the new object the headers of the stack, such as api_key and branch. addHeader changes only this object.

Rate limiting and retry.

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

Additional Resource The Contentstack class covers the retry options of contentstack.client() and their defaults.

Capability Matrix

CapabilitySupportedNotes / Alternative
Publish more items than the API limit in one callNoSplit the items into batches and send one request per batch
List all the bulk jobs of a stackNoThe SDK has no method for the bulk task queue. Keep the job ID of each bulk request
Wait for a bulk job to finishNoCall jobStatus at an interval until the job completes

Method Index

Publish, unpublish and delete in bulk. The methods in the table below are available on stack.bulkOperation().

Method NameReturnsDescription
publishThe API response with a notice.Publishes entries and assets in bulk.
unpublishThe API response with a notice.Unpublishes entries and assets in bulk.
deleteThe API response with a notice.Deletes entries and assets in bulk.
updateThe API response with a notice.Changes the workflow details of entries in bulk.

Manage release items in bulk. The methods in the table below are available on stack.bulkOperation().

Method NameReturnsDescription
addItemsThe API response, or undefined when the request fails.Adds entries and assets to a release.
updateItemsThe API response, or undefined when the request fails.Updates the items of a release.

Track bulk jobs. The methods in the table below are available on stack.bulkOperation().

Method NameReturnsDescription
jobStatusThe job details, or undefined when the request fails.Retrieves the status of a bulk job.
getJobItemsThe job items, or undefined when the request fails.Lists the items of a bulk job.

Set request headers. The methods in the table below are available on stack.bulkOperation().

Method NameReturnsDescription
addHeaderThe same bulk operation object, for chaining.Adds one request header.
addHeaderDictThe same bulk operation object, for chaining.Adds several request headers.
removeHeaderThe same bulk operation object, for chaining.Removes one request header.

Class-Level Snippet

The snippet below publishes one entry and one asset on one environment and locale in a single bulk request.

import contentstack from '@contentstack/management'

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

const details = {
  entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
  assets: [{ uid: '<ASSET_UID>' }],
  locales: ['<LOCALE>'],
  environments: ['<ENVIRONMENT>']
}

try {
  const response = await stack.bulkOperation().publish({ details })
  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)
}

Methods

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

addHeader

addHeader adds one header to every request that this bulk operation object sends afterwards.

NameTypeDescription
key (required)string

Name of the request header.

Default: Not applicable
value (required)string

Value of the request header.

Default: Not applicable

Returns: BulkOperation. The same bulk operation object, for chaining.

Validation

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

Behavior

  • Client-side only. addHeader stores the header on this bulk operation object and sends no request.
  • The first header method call on this object copies the headers it received from the stack, so the change applies to this bulk operation object only. The stack and other objects keep their headers.
  • Every later request from this object sends the header. A key that already exists, such as branch, takes the new value.

Example

Basic usage: send this object's requests to another branch

import contentstack from '@contentstack/management'

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

const bulk = stack.bulkOperation().addHeader('branch', '<BRANCH>')
console.log(bulk.stackHeaders)

addHeaderDict

addHeaderDict adds several headers to every request that this bulk operation object sends afterwards.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: BulkOperation. The same bulk operation object, for chaining.

Validation

  • There is no client-side validation of the names or the values.
  • A headerDict that is null, undefined or not an object leaves the headers unchanged, and addHeaderDict returns the object without an error.
  • An invalid header surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeaderDict copies each key and value of headerDict into the headers of this bulk operation object and sends no request.
  • The first header method call on this object copies the headers it received from the stack, so the change applies to this bulk operation object only. The stack and other objects keep their headers.
  • A key that already exists, such as branch, takes the new value.

Example

Basic usage: add a branch and a request ID in one call

import contentstack from '@contentstack/management'

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

const bulk = stack.bulkOperation().addHeaderDict({
  branch: '<BRANCH>',
  'x-request-id': 'docs-123'
})
console.log(bulk.stackHeaders)

addItems

addItems adds many entries and assets to a release in one request. The following table lists its parameters.

NameTypeDescription
options (required)BulkAddItemsConfig

Request body and the bulk version.

Default: Not applicable
options.data (required)AnyProperty

Request body with the release and items.

Default: Not applicable
options.data.release (required)string

UID of the target release.

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

publish or unpublish.

Default: Not applicable
options.data.locale (required)string[]

Locale codes of the entries.

Default: Not applicable
options.data.referenceboolean

Adds the referenced items too.

Default: API default
options.data.items (required)object[]

Items, by uid, content_type_uid, locale, version and title.

Default: Not applicable
options.bulk_versionstring

Bulk version header. The API requires 2.0.

Default: '' (not sent)

Returns: Promise<Response>. The API response, or undefined when the request fails.

Known issue When the request fails, addItems writes the error to the console and resolves to undefined instead of rejecting. Check the result for undefined before you read it.

Validation

  • There is no client-side validation. The SDK sends options.data as you pass it.
  • Calling addItems() with no argument returns a promise that rejects with TypeError, because addItems reads its options from one object.
  • An API rejection or a network failure does not reject the promise. See the Known issue above.

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

Behavior

  • One call sends one Bulk Add to Release request (POST /v3/bulk/release/items) with options.data as the JSON body.
  • A non-empty options.bulk_version goes as the bulk_version header. The API needs bulk_version: 2.0 for this request, so always pass '2.0'.
  • With reference: true, the API also adds the items that the listed entries reference.
  • The API adds the items in a background job. addItems resolves to the response body when the API accepts the request.

Example

Basic usage: add two entries to a release for publishing

import contentstack from '@contentstack/management'

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

const data = {
  release: '<RELEASE_UID>',
  action: 'publish',
  locale: ['<LOCALE>'],
  items: [
    { uid: '<ENTRY_UID>', content_type_uid: '<CONTENT_TYPE_UID>', locale: '<LOCALE>', version: 1, title: 'Spring campaign' }
  ]
}

try {
  const response = await stack.bulkOperation().addItems({ data, bulk_version: '2.0' })
  if (response === undefined) {
    // The request failed. The SDK wrote the error to the console.
    console.error('Bulk add to release failed')
  } else {
    console.log(response.notice)
  }
} catch (error) {
  // A missing options object rejects here
  console.error(error.message)
}

All parameters: add entries with their referenced items

import contentstack from '@contentstack/management'

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

const data = {
  release: '<RELEASE_UID>',
  action: 'publish',
  locale: ['<LOCALE>'],
  reference: true,
  items: [
    { uid: '<ENTRY_UID>', content_type_uid: '<CONTENT_TYPE_UID>', locale: '<LOCALE>', version: 1, title: 'Spring campaign' }
  ]
}

try {
  const response = await stack.bulkOperation().addItems({ data, bulk_version: '2.0' })
  console.log(response ? response.notice : 'Bulk add to release failed')
} catch (error) { console.error(error.message) }

delete

delete deletes many entries and assets in one request.

NameTypeDescription
paramsBulkDeleteConfig

Options with the items to delete.

Default: {}
params.details (required)object

Request body with the entries and assets.

Default: Not applicable
params.details.entriesBulkDeleteEntry[]

Entries, by uid, content_type and locale.

Default: undefined (not sent)
params.details.assetsBulkDeleteAsset[]

Assets, by uid.

Default: undefined (not sent)

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

Warning delete removes every listed entry and asset from the stack, and the SDK has no method that restores them.

Validation

  • There is no client-side validation. The SDK sends params.details as you pass it.
  • 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

  • One call sends one Delete entries and assets in bulk request (POST /v3/bulk/delete) with params.details as the JSON body.
  • delete reads only params.details. It ignores entries and assets at the top level of params, and then sends an empty body.
  • One request deletes up to 100 entries.
  • delete resolves to the response body, which holds notice.

Example

Basic usage: delete an entry and an asset

import contentstack from '@contentstack/management'

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

const details = {
  entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
  assets: [{ uid: '<ASSET_UID>' }]
}

try {
  const response = await stack.bulkOperation().delete({ details })
  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)
}

getJobItems

getJobItems lists the items of one bulk publish or unpublish job, with the status of each item. The following table lists its parameters.

NameTypeDescription
job_id (required)string

ID of the bulk job.

Default: Not applicable
paramsBulkJobItemsParams

Query parameters and the API version.

Default: {}
params.api_versionstring

API version header. An empty string sends none.

Default: '3.2'
params.include_countboolean

Adds the total number of items.

Default: API default (false)
params.skipnumber

Number of items to skip.

Default: API default (0)
params.limitnumber

Number of items to return, at most 100.

Default: API default (100)
params.include_referenceboolean

Adds the referenced items.

Default: API default (false)
params.statusstring

success or failed.

Default: API default
params.typestring

entry or asset.

Default: API default
params.ctstring[] | string

Content type UIDs to filter by.

Default: API default

Returns: Promise<BulkJobItemsResponse>. The job items, or undefined when the request fails.

Known issue When the request fails, getJobItems writes the error to the console and resolves to undefined instead of rejecting. Check the result for undefined before you read it.

Validation

  • There is no client-side validation. A missing job_id puts undefined in the request path.
  • An API rejection or a network failure does not reject the promise. See the Known issue above.

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

Behavior

  • One call sends one Get job items status request (GET /v3/bulk/jobs/{job_id}/items).
  • The SDK sends params.api_version as the api_version header, 3.2 by default. It sends every other key of params as a query parameter.
  • Pass ct as an array, so that the SDK sends one ct[] parameter per content type. A string goes as ct without brackets.
  • The API returns the first 100 items at most. Use skip and limit to read the rest. The API returns the count only when skip is 0 or absent.
  • The response holds items, and skip, limit and total_count when you pass include_count: true.

Example

Basic usage: list the items of a bulk job

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.bulkOperation().getJobItems('<JOB_UID>')
  if (result === undefined) {
    // The request failed. The SDK wrote the error to the console.
    console.error('Job items request failed')
  } else {
    result.items.forEach((item) => console.log(item.uid, item.publish_details.status))
  }
} catch (error) {
  console.error(error.message)
}

All parameters: list the failed entries of two content types

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.bulkOperation().getJobItems('<JOB_UID>', {
    api_version: '3.2',
    include_count: true,
    skip: 0,
    limit: 50,
    include_reference: true,
    status: 'failed',
    type: 'entry',
    ct: ['<CONTENT_TYPE_UID>', 'author']
  })
  console.log(result ? result.total_count : 'Job items request failed')
} catch (error) { console.error(error.message) }

jobStatus

jobStatus retrieves the status and details of one bulk publish or unpublish job.

NameTypeDescription
options (required)BulkJobStatus

Job ID and version headers.

Default: Not applicable
options.job_id (required)string

ID of the bulk job.

Default: Not applicable
options.bulk_versionstring

Bulk version header.

Default: '' (not sent)
options.api_versionstring

API version header. The API requires 3.2.

Default: '' (not sent)

Returns: Promise<Response>. The job details, or undefined when the request fails.

Known issue When the request fails, jobStatus writes the error to the console and resolves to undefined instead of rejecting. Check the result for undefined before you read it.

Validation

  • There is no client-side validation. A missing job_id puts undefined in the request path.
  • Calling jobStatus() with no argument returns a promise that rejects with TypeError, because jobStatus reads its options from one object.
  • An API rejection or a network failure does not reject the promise. See the Known issue above.

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

Behavior

  • One call sends one Get job status request (GET /v3/bulk/jobs/{job_id}).
  • A non-empty bulk_version or api_version goes as a header of the same name. The API reference asks for api_version: 3.2, so pass it.
  • jobStatus resolves to the response body as a plain object.

Example

Basic usage: read the status of a bulk job

import contentstack from '@contentstack/management'

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

try {
  const job = await stack.bulkOperation().jobStatus({ job_id: '<JOB_UID>', api_version: '3.2' })
  if (job === undefined) {
    // The request failed. The SDK wrote the error to the console.
    console.error('Job status request failed')
  } else {
    console.log(JSON.stringify(job, null, 2))
  }
} catch (error) {
  // A missing options object rejects here
  console.error(error.message)
}

All parameters: read the status with both version headers

import contentstack from '@contentstack/management'

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

try {
  const job = await stack.bulkOperation().jobStatus({ job_id: '<JOB_UID>', bulk_version: '2.0', api_version: '3.2' })
  console.log(job ? JSON.stringify(job) : 'Job status request failed')
} catch (error) { console.error(error.message) }

publish

publish publishes many entries and assets on the environments and locales you name, in one request.

NameTypeDescription
options (required)BulkOperationConfig

Items, targets and request options.

Default: Not applicable
options.details (required)PublishItems

Request body with the items and targets.

Default: Not applicable
options.details.entriesBulkOperationItem[]

Entries, by uid, content_type, locale and version.

Default: undefined (not sent)
options.details.assetsBulkOperationItem[]

Assets, by uid.

Default: undefined (not sent)
options.details.locales (required)string[]

Locale codes to publish on.

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

Environment names to publish on.

Default: Not applicable
options.skip_workflow_stageboolean

Sends the skip_workflow_stage_check header.

Default: false
options.approvalsboolean

Sends the approvals header.

Default: false
options.is_nestedboolean

Adds nested=true and event_type=bulk to the query.

Default: false
options.api_versionstring

API version header, 3.2 for nested references.

Default: '' (not sent)
options.publishAllLocalizedboolean

Adds publish_all_localized=true to the query.

Default: false

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

Validation

  • There is no client-side validation. The SDK sends options.details as you pass it, or an empty body when you omit it.
  • Calling publish() with no argument returns a promise that rejects with TypeError, because publish reads its options from one object.
  • 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

  • One call sends one Publish entries and assets in bulk request (POST /v3/bulk/publish) with options.details as the JSON body.
  • The SDK maps each option to the request as follows:
    • skip_workflow_stage: true sends the header skip_workflow_stage_check: true.
    • approvals: true sends the header approvals: true.
    • is_nested: true adds the query parameters nested=true and event_type=bulk.
    • api_version sends the header api_version.
    • publishAllLocalized: true adds the query parameter publish_all_localized=true.
  • The API reference lists skip_workflow_stage_check and approvals as query parameters. The SDK sends them as headers.
  • With skip_workflow_stage_check, the API publishes the entries whose workflow stage satisfies the publish rules. With approvals, it publishes the entries that need no approval.
  • To publish nested references up to five levels deep with their parent entries, pass api_version: '3.2'.
  • When you omit version on an entry, the API publishes its latest version.
  • The API publishes the items in a background job. publish resolves to the response body, which holds notice, when the API accepts the request.

Example

Basic usage: publish an entry and an asset

import contentstack from '@contentstack/management'

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

const details = {
  entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>', version: 1 }],
  assets: [{ uid: '<ASSET_UID>' }],
  locales: ['<LOCALE>'],
  environments: ['<ENVIRONMENT>']
}

try {
  const response = await stack.bulkOperation().publish({ details })
  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: publish nested references in all localized versions

import contentstack from '@contentstack/management'

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

const details = {
  entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
  assets: [{ uid: '<ASSET_UID>' }],
  locales: ['<LOCALE>'],
  environments: ['<ENVIRONMENT>']
}

try {
  const response = await stack.bulkOperation().publish({
    details,
    skip_workflow_stage: true,
    approvals: true,
    is_nested: true,
    api_version: '3.2',
    publishAllLocalized: true
  })
  console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }

removeHeader

removeHeader removes one header from the requests that this bulk operation object sends afterwards.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: BulkOperation. The same bulk operation object, 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, and removeHeader returns the object without an error.
  • Removing api_key makes the next request fail with an API error, because every stack request needs the API key.

Behavior

  • Client-side only. removeHeader deletes the header from this bulk operation object and sends no request.
  • When the header came from the stack, the SDK first copies the headers, so the stack and other objects keep it.
  • The management token and the authtoken live on the client, not on this object. removeHeader('authorization') does not remove them.

Example

Basic usage: stop sending the branch header from one object

import contentstack from '@contentstack/management'

const client = contentstack.client()
// This stack sends a branch header on every request
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

const bulk = stack.bulkOperation().removeHeader('branch')
console.log(bulk.stackHeaders)

unpublish

unpublish unpublishes many entries and assets from the environments and locales you name, in one request.

NameTypeDescription
options (required)BulkOperationConfig

Items, targets and request options.

Default: Not applicable
options.details (required)PublishItems

Request body with the items and targets.

Default: Not applicable
options.details.entriesBulkOperationItem[]

Entries, by uid, content_type, locale and version.

Default: undefined (not sent)
options.details.assetsBulkOperationItem[]

Assets, by uid.

Default: undefined (not sent)
options.details.locales (required)string[]

Locale codes to unpublish from.

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

Environment names to unpublish from.

Default: Not applicable
options.skip_workflow_stageboolean

Sends the skip_workflow_stage_check header.

Default: false
options.approvalsboolean

Sends the approvals header.

Default: false
options.is_nestedboolean

Adds nested=true and event_type=bulk to the query.

Default: false
options.api_versionstring

API version header, 3.2 for nested references.

Default: '' (not sent)
options.unpublishAllLocalizedboolean

Adds publish_all_localized=true to the query.

Default: false

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

Warning unpublish removes every listed item from the environments you name, so delivery requests on those environments stop returning them. Publish the items again to restore them.

Validation

  • There is no client-side validation. The SDK sends options.details as you pass it, or an empty body when you omit it.
  • Calling unpublish() with no argument returns a promise that rejects with TypeError, because unpublish reads its options from one object.
  • 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

  • One call sends one Unpublish entries and assets in bulk request (POST /v3/bulk/unpublish) with options.details as the JSON body.
  • The SDK maps each option to the request as follows:
    • skip_workflow_stage: true sends the header skip_workflow_stage_check: true.
    • approvals: true sends the header approvals: true.
    • is_nested: true adds the query parameters nested=true and event_type=bulk.
    • api_version sends the header api_version.
    • unpublishAllLocalized: true adds the query parameter publish_all_localized=true, the same parameter that publish uses.
  • The API reference lists skip_workflow_stage_check and approvals as query parameters. The SDK sends them as headers.
  • With api_version: '3.2', the API logs the unpublish task in the nested reference flow.
  • The API unpublishes the items in a background job. unpublish resolves to the response body, which holds notice, when the API accepts the request.

Example

Basic usage: unpublish an entry and an asset

import contentstack from '@contentstack/management'

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

const details = {
  entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
  assets: [{ uid: '<ASSET_UID>' }],
  locales: ['<LOCALE>'],
  environments: ['<ENVIRONMENT>']
}

try {
  const response = await stack.bulkOperation().unpublish({ details })
  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: unpublish nested references in all localized versions

import contentstack from '@contentstack/management'

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

const details = {
  entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
  locales: ['<LOCALE>'],
  environments: ['<ENVIRONMENT>']
}

try {
  const response = await stack.bulkOperation().unpublish({
    details,
    skip_workflow_stage: true,
    approvals: true,
    is_nested: true,
    api_version: '3.2',
    unpublishAllLocalized: true
  })
  console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }

update

update changes the workflow stage, assignees, due date and comment of many entries in one request.

NameTypeDescription
updateBodyobject

Request body with the entries and workflow details.

Default: {}
updateBody.entries (required)object[]

Entries, by uid, content_type and locale.

Default: Not applicable
updateBody.workflow.workflow_stage.uid (required)string

UID of the new workflow stage.

Default: Not applicable
updateBody.workflow.workflow_stage.commentstring

Comment for the assigned users.

Default: undefined (not sent)
updateBody.workflow.workflow_stage.due_datestring

Due date for the stage.

Default: undefined (not sent)
updateBody.workflow.workflow_stage.notifyboolean

Notifies the assigned users.

Default: API default
updateBody.workflow.workflow_stage.assigned_toobject[]

Users to assign, by uid, name and email.

Default: undefined (not sent)
updateBody.workflow.workflow_stage.assigned_by_rolesobject[]

Roles to assign, by uid and name.

Default: undefined (not sent)

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

Validation

  • There is no client-side validation. The SDK sends updateBody as you pass it.
  • 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.
  • The API changes the stage only when every listed entry sits at the same workflow stage of the same workflow.

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

Behavior

  • One call sends one Update workflow details in bulk request (POST /v3/bulk/workflow) with updateBody as the JSON body.
  • Unlike the other bulk methods, update takes the request body itself, not an options object with details.
  • update resolves to the response body, which holds notice.

Example

Basic usage: move two entries to the next workflow stage

import contentstack from '@contentstack/management'

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

const updateBody = {
  entries: [
    { uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }
  ],
  workflow: {
    workflow_stage: { uid: '<WORKFLOW_STAGE_UID>' }
  }
}

try {
  const response = await stack.bulkOperation().update(updateBody)
  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: change the stage, assign a user and a role, and notify them

import contentstack from '@contentstack/management'

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

const updateBody = {
  entries: [
    { uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }
  ],
  workflow: {
    workflow_stage: {
      uid: '<WORKFLOW_STAGE_UID>',
      comment: 'Ready for legal review',
      due_date: '2026-12-01',
      notify: true,
      assigned_to: [{ uid: '<USER_UID>', name: 'Jane Doe', email: '<COLLABORATOR_EMAIL>' }],
      assigned_by_roles: [{ uid: '<ROLE_UID>', name: 'Content Manager' }]
    }
  }
}

try {
  const response = await stack.bulkOperation().update(updateBody)
  console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }

updateItems

updateItems updates the items of a release in bulk, for example to their latest versions.

NameTypeDescription
options (required)BulkAddItemsConfig

Request body and the bulk version.

Default: Not applicable
options.data (required)AnyProperty

Request body with the release and items.

Default: Not applicable
options.bulk_versionstring

Bulk version header, for example 2.0.

Default: '' (not sent)

Returns: Promise<Response>. The API response, or undefined when the request fails.

Known issue When the request fails, updateItems writes the error to the console and resolves to undefined instead of rejecting. Check the result for undefined before you read it.

Validation

  • There is no client-side validation. The SDK sends options.data as you pass it.
  • Calling updateItems() with no argument returns a promise that rejects with TypeError, because updateItems reads its options from one object.
  • An API rejection or a network failure does not reject the promise. See the Known issue above.

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

Behavior

  • One call sends one PUT /v3/bulk/release/update_items request with options.data as the JSON body.
  • A non-empty options.bulk_version goes as the bulk_version header.
  • The body names the release and the items. items: ['$all'] selects every item in the release, as in the Update Release items to their latest versions request.
  • updateItems resolves to the response body when the API accepts the request.

Example

Basic usage: update every item of a release to its latest version

import contentstack from '@contentstack/management'

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

const data = {
  release: '<RELEASE_UID>',
  action: 'publish',
  locale: ['<LOCALE>'],
  reference: true,
  items: ['$all']
}

try {
  const response = await stack.bulkOperation().updateItems({ data, bulk_version: '2.0' })
  if (response === undefined) {
    // The request failed. The SDK wrote the error to the console.
    console.error('Bulk update of release items failed')
  } else {
    console.log(response.notice)
  }
} catch (error) {
  // A missing options object rejects here
  console.error(error.message)
}