Release

View as Markdown

Release

A release is a set of entries and assets, each with a publish or unpublish action, that you deploy to environments in one step. Use the Release class to do the following tasks:

  • create, list, fetch, rename, lock or delete a release
  • clone a release
  • deploy a release to environments and locales, now or at a scheduled time
  • open the ReleaseItem class to add, list, move or remove the items of a release

The release method on Stack returns a new Release and sends no request.

Additional Resource The Releases section of the Content Management API (CMA) reference describes every release request and its response.

Instance State

The form you call decides which methods the object has:

  • Call stack.release() without a UID to work on the collection (create, query).
  • Call stack.release('<RELEASE_UID>') to work on one release (fetch, deploy).
  • The three header methods exist on both forms.

The Method Index below lists the full set for each form. A method of the other form is undefined on the object, and calling it throws TypeError.

Warning stack.release(''), stack.release(null) and stack.release(undefined) return the collection form, because the SDK treats an empty UID as no UID. Nothing fails at that point. The fetch call that follows throws TypeError. Check that the UID variable is non-empty before you call stack.release.

Class-Level Notes

Requests and responses.

  • Every request method is async and sends one request when you call it. stack.release() and item send no request.
  • create, fetch, update and clone resolve to a new Release that the SDK builds from the release key of the response.
  • When the response contains items, the SDK turns each item into a ReleaseItem object in the items property.

Release version header.

  • The API reference asks for the release_version: 2.0 header when the latest release feature is on for your organization. Set it on a release object with addHeader, for example stack.release('<RELEASE_UID>').addHeader('release_version', '2.0').
  • The ReleaseItem methods take release_version as an option instead.

Headers and branches.

  • stack.release() 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
Lock a release, or remove its lock, with its own methodNoSet locked to true or false and call update
Update all items to their latest versionsNoUse the updateItems method of BulkOperation
Use a cloned release object for more requestsNoCall stack.release(clone.uid) for a new object. See the Known issue on clone

Class-Level Properties

PropertyTypeAccessDefaultDescription
uidstringReadThe UID passed to stack.release()UID of the release.
itemsReleaseItem[]Read and writeundefined until a response holds itemsItems of the release, as ReleaseItem objects.

Method Index

The first group works on stack.release(). The second group works on stack.release('<RELEASE_UID>'). The last group works on both forms.

Create and list releases. The methods in the table below are available on stack.release().

Method NameReturnsDescription
createThe new release.Creates a release.
queryA query for releases, sent when you call find(), findOne() or count().Builds a query for the releases of the stack.

Work with one release. The methods in the table below are available on stack.release('<RELEASE_UID>').

Method NameReturnsDescription
fetchThe requested release.Retrieves one release.
updateThe updated release.Saves the name, description or lock state.
deployThe API response with the deploy notice.Deploys the release to environments.
cloneThe new copy of the release.Copies a release.
itemA new release item object.Returns a ReleaseItem for item requests.
deleteThe API response with a notice.Deletes the release.

Set request headers. The methods in the table below are available on both forms.

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

Class-Level Snippet

The snippet below creates a release, adds one entry to it for publishing, and deploys it to one environment and locale.

import contentstack from '@contentstack/management'

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

try {
  const release = await stack.release().create({ release: { name: 'docs-test-spring-campaign' } })
  await release.item().create({
    item: { uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }
  })
  const response = await release.deploy({ environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'], action: 'publish' })
  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 Release class has its own section below, with its parameters, validation rules, behavior, and examples.

addHeader

addHeader adds one header to every request that this release 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: Release. The same release, 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 release 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 release 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.
  • The ReleaseItem that item returns afterwards starts with these headers.

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 release = stack.release('<RELEASE_UID>').addHeader('branch', '<BRANCH>')
console.log(release.stackHeaders)

addHeaderDict

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

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: Release. The same release, 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 release 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 release object only. The stack and other objects keep their headers.
  • A key that already exists, such as branch, takes the new value.
  • The ReleaseItem that item returns afterwards starts with these headers.

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 release = stack.release('<RELEASE_UID>').addHeaderDict({
  branch: '<BRANCH>',
  'x-request-id': 'docs-123'
})
console.log(release.stackHeaders)

clone

clone creates a copy of a release under a new name.

NameTypeDescription
options (required)object

Name and description of the copy.

Default: Not applicable
options.name (required)string

Name of the new release.

Default: Not applicable
options.descriptionstring

Description of the new release.

Default: undefined (not sent)

Returns: Promise<Release>. The new copy of the release.

Known issue The Release that clone returns has no stack headers, so a request from it, such as fetch or deploy, goes out without the api_key header and the API rejects it. Read uid from the result and call stack.release(uid) to work on the copy.

Validation

  • There is no client-side validation.
  • Calling clone() with no argument returns a promise that rejects with TypeError, because clone reads its options from one object.
  • clone exists only on stack.release('<RELEASE_UID>'). On stack.release() 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

  • One call sends one Clone a Release request (POST /v3/releases/{release_uid}/clone) with the body { "release": { name, description } }.
  • clone resolves to a new Release that the SDK builds from the release key of the response.

Example

Basic usage: clone a release and deploy the copy

import contentstack from '@contentstack/management'

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

try {
  const copy = await stack.release('<RELEASE_UID>').clone({ name: 'docs-test-spring-campaign-copy' })
  // Work on the copy through a new object from the stack
  const release = stack.release(copy.uid)
  const response = await release.deploy({ environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'], action: 'publish' })
  console.log(copy.uid, 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: clone a release with a description

import contentstack from '@contentstack/management'

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

try {
  const copy = await stack.release('<RELEASE_UID>').clone({
    name: 'docs-test-spring-campaign-copy',
    description: 'Copy of the spring campaign release'
  })
  console.log(copy.uid, copy.name)
} catch (error) { console.error(error.errorMessage) }

create

create creates a release in the stack.

NameTypeDescription
data (required){ release: ReleaseData }

Request body with the release under a release key.

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

Name of the release.

Default: Not applicable
data.release.descriptionstring

Description of the release.

Default: undefined (not sent)
data.release.lockedboolean

Locks the release against changes.

Default: API default
data.release.archivedboolean

Marks the release as archived.

Default: API default
paramAnyProperty

Query parameters for the request.

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

Adds the _branch key to the release.

Default: API default

Returns: Promise<Release>. The new release.

Validation

  • There is no client-side validation. The SDK sends data as you pass it.
  • create exists only on stack.release(). On stack.release('<RELEASE_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.
  • The API rejects a release without a name, because name is the one field the request needs.

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

Behavior

  • One call sends one Create a Release request (POST /v3/releases) with data as the JSON body and param as query parameters.
  • create resolves to a new Release that the SDK builds from the release key of the response. The new object has the single-release methods, such as item and deploy.
  • To add entries and assets, call the create method of ReleaseItem on the new release.

Example

Basic usage: create a release

import contentstack from '@contentstack/management'

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

try {
  const release = await stack.release().create({ release: { name: 'docs-test-spring-campaign' } })
  console.log(release.uid, release.name)
} 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 release with a description and no lock

import contentstack from '@contentstack/management'

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

try {
  const release = await stack.release().create(
    {
      release: {
        name: 'docs-test-spring-campaign',
        description: 'Entries and assets for the spring campaign',
        locked: false,
        archived: false
      }
    },
    { include_branch: true }
  )
  console.log(release.uid, release._branch)
} catch (error) { console.error(error.errorMessage) }

delete

delete deletes a release from the stack.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}

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

Warning delete removes the release and its list of items, and the SDK has no method that restores it. The entries and assets in the release stay in the stack.

Validation

  • There is no client-side validation.
  • delete exists only on stack.release('<RELEASE_UID>'). On stack.release() 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

  • One call sends one Delete a Release request (DELETE /v3/releases/{release_uid}) with param as query parameters.
  • The SDK sends the request without a Content-Type header, because the request has no body.
  • delete resolves to the response body, which holds notice. When the response has no body, it resolves to { status, statusText }.

Example

Basic usage: delete a release

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.release('<RELEASE_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 a release and pass query parameters

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.release('<RELEASE_UID>').delete({ include_branch: true })
  console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }

deploy

deploy publishes or unpublishes every item of a release on the environments and locales you name, now or at a scheduled time.

NameTypeDescription
options (required)ReleaseDeploy

Targets, action and schedule.

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

Environment names to deploy to.

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

Locale codes to deploy to.

Default: Not applicable
options.action (required)string

publish or unpublish.

Default: Not applicable
options.scheduledAtstring

ISO 8601 date and time to deploy later.

Default: undefined (not sent)

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

Validation

  • There is no client-side validation. The SDK sends the four values as you pass them.
  • Calling deploy() with no argument returns a promise that rejects with TypeError, because deploy reads its options from one object.
  • deploy exists only on stack.release('<RELEASE_UID>'). On stack.release() 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

  • One call sends one Deploy a Release request (POST /v3/releases/{release_uid}/deploy).
  • The SDK builds the JSON body as { "release": { environments, locales, scheduledAt, action } }. It keeps the name scheduledAt as written, and leaves out any value that is undefined.
  • deploy reads only these four options. It ignores any other key.
  • deploy resolves to the response body, which holds notice.

Example

Basic usage: deploy a release now

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.release('<RELEASE_UID>').deploy({
    environments: ['<ENVIRONMENT>'],
    locales: ['<LOCALE>'],
    action: 'publish'
  })
  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 a deploy to two environments

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.release('<RELEASE_UID>').deploy({
    environments: ['<ENVIRONMENT>', 'staging'],
    locales: ['<LOCALE>'],
    action: 'publish',
    scheduledAt: '2026-12-01T09:00:00.000Z'
  })
  console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }

fetch

fetch retrieves the details of one release.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}
param.include_branchboolean

Adds the _branch key to the release.

Default: API default

Returns: Promise<Release>. The requested release.

Validation

  • There is no client-side validation.
  • fetch exists only on stack.release('<RELEASE_UID>'). On stack.release() 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

  • One call sends one Get a single Release request (GET /v3/releases/{release_uid}) with param as query parameters.
  • fetch resolves to a new Release that the SDK builds from the release key of the response.
  • When the response holds items, the new object holds them as an array of ReleaseItem objects in items.
  • A fetched release sends items back when you call update on it. To change only the name or description, see the update page.

Example

Basic usage: retrieve a release and its items

import contentstack from '@contentstack/management'

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

try {
  const release = await stack.release('<RELEASE_UID>').fetch()
  console.log(release.name, release.locked)
  const items = release.items || []
  items.forEach((item) => console.log(item.uid, item.action))
} 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: retrieve a release with the branch key

import contentstack from '@contentstack/management'

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

try {
  const release = await stack.release('<RELEASE_UID>').fetch({ include_branch: true })
  console.log(release.name, release._branch)
} catch (error) { console.error(error.errorMessage) }

item

item returns a new ReleaseItem object for the items of this release and sends no request.

This method takes no parameters.

Returns: ReleaseItem. A new release item object.

Validation

  • There is no client-side validation.
  • item exists only on stack.release('<RELEASE_UID>'). On stack.release() 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

  • The new ReleaseItem has create, findAll, move and delete. Each method acts on the items of this release.
  • The new object starts with the headers of this release object, such as api_key and branch.
  • Call item() again for each request. A ReleaseItem keeps state between calls, as the ReleaseItem class page explains.

Example

Basic usage: list the items of a release

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.release('<RELEASE_UID>').item().findAll()
  result.items.forEach((item) => console.log(item.uid, item.action, item.locale))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

query

query builds a query for the releases of the stack. It sends no request until you call find(), findOne() or count().

NameTypeDescription
paramsobject

Query parameters for the request.

Default: {}
params.include_countboolean

Adds the total number as count.

Default: API default
params.include_items_countboolean

Adds the number of items in each release.

Default: API default
params.limitnumber

Number of releases to return.

Default: API default
params.skipnumber

Number of releases to skip.

Default: API default
params.include_branchboolean

Adds the _branch key to each release.

Default: API default

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

Validation

  • There is no client-side validation.
  • query exists only on stack.release(). On stack.release('<RELEASE_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

  • query copies the headers of this object and params into a new Query object and sends nothing.
  • find sends one Get all Releases request (GET /v3/releases). It resolves to a ContentstackCollection whose items are Release objects with the single-release methods.
  • The API returns the most recently updated releases first.
  • The SDK does not page through results. Use limit and skip to read the next page.

Example

Basic usage: list the releases of a stack

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.release().query().find()
  result.items.forEach((release) => console.log(release.uid, release.name))
} 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 five, with counts

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.release().query({
    include_count: true,
    include_items_count: true,
    limit: 5,
    skip: 5,
    include_branch: true
  }).find()
  console.log(result.count)
  result.items.forEach((release) => console.log(release.name))
} catch (error) { console.error(error.errorMessage) }

removeHeader

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

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: Release. The same release, 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 release 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 release = stack.release('<RELEASE_UID>').removeHeader('branch')
console.log(release.stackHeaders)

update

update saves the name, description and lock state that you set on a release object.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}
param.include_branchboolean

Adds the _branch key to the release.

Default: API default

Returns: Promise<Release>. The updated release.

Validation

  • There is no client-side validation. update sends whatever properties the object holds.
  • update exists only on stack.release('<RELEASE_UID>'). On stack.release() 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

  • One call sends one Update a Release request (PUT /v3/releases/{release_uid}) with param as query parameters.
  • update takes no body argument. The SDK builds the body as { "release": { ... } } from the properties of the object. It leaves out uid, urlPath, stackHeaders, api_key and the created, updated and deleted metadata.
  • Set name and description to rename the release. Set locked to true to lock it, or to false to remove the lock.
  • On a release from fetch, the body also carries the fetched items array, including the SDK data of each item. To send only the fields you change, set them on stack.release('<RELEASE_UID>') without a fetch.
  • update resolves to a new Release that the SDK builds from the response.

Example

Basic usage: rename a release

import contentstack from '@contentstack/management'

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

try {
  // No fetch, so the request body holds only the name and description
  const release = stack.release('<RELEASE_UID>')
  release.name = 'Spring campaign'
  release.description = 'Entries and assets for the spring campaign'
  const updated = await release.update()
  console.log(updated.name)
} 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: lock a release and include the branch key

import contentstack from '@contentstack/management'

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

try {
  const release = stack.release('<RELEASE_UID>')
  release.locked = true
  const updated = await release.update({ include_branch: true })
  console.log(updated.locked, updated._branch)
} catch (error) { console.error(error.errorMessage) }