ReleaseItem
ReleaseItem
A release item is one entry or asset in a release, with the action to apply on deploy and the version and locale to use. Use the ReleaseItem class to add items to a release, list them, move them to another release, or remove them.
The item method on stack.release('<RELEASE_UID>') returns a new ReleaseItem for that release and sends no request.
Additional Resource The Release Items requests of the Content Management API (CMA) reference describe each item request and its body.
Instance State
- stack.release('<RELEASE_UID>').item() returns an object with every method in the Method Index below. Each method acts on the items of that release.
- item exists only on a release with a UID. On stack.release() it is undefined, and calling it throws TypeError.
- The objects in the items array of a findAll result are also ReleaseItem objects. Each one holds the item fields, such as uid, version, locale, content_type_uid and action, and has the same methods.
Class-Level Notes
One object per request.
- A ReleaseItem stores its request path. A call to create or delete with a single item changes that path for every later call on the same object. Each of those two method pages includes a Known issue line.
- Call release.item() again for each request, so that each call starts from the right path.
Item fields.
- Each item names its entry or asset with uid, its version, its locale, its content_type_uid and its action (publish or unpublish).
- For an asset, the API expects content_type_uid: 'built_io_upload'.
Release version header.
- Every method takes a release_version option and sends it as the release_version header. The API reference requires 2.0 when the latest release feature is on for your organization.
Headers and branches.
- The object starts with the headers of the release object that created it, 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.
Method Index
Add and list items. The methods in the table below are available on stack.release('<RELEASE_UID>').item().
| Method Name | Returns | Description |
|---|---|---|
| create | The updated release. | Adds one or more items to the release. |
| findAll | The items of the release. | Lists the items of the release. |
Move and remove items. The methods in the table below are available on stack.release('<RELEASE_UID>').item().
| Method Name | Returns | Description |
|---|---|---|
| move | The API response body. | Moves items to another release. |
| delete | The API response with a notice. | Removes items, or all items, from the release. |
Set request headers. The methods in the table below are available on stack.release('<RELEASE_UID>').item().
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same release item object, for chaining. | Adds one request header. |
| addHeaderDict | The same release item object, for chaining. | Adds several request headers. |
| removeHeader | The same release item object, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below adds an entry and an asset to a release and then lists the items of the release.
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>')
try {
await release.item().create({
items: [
{ uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' },
{ uid: '<ASSET_UID>', version: 1, locale: '<LOCALE>', content_type_uid: 'built_io_upload', action: 'publish' }
]
})
const result = await release.item().findAll()
result.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)
}Methods
Each method of the ReleaseItem 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 item object sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the request header. |
| value (required) | string | Value of the request header. |
Returns: ReleaseItem. The same release item 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 release item 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 item 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 items = stack.release('<RELEASE_UID>').item().addHeader('branch', '<BRANCH>')
console.log(items.stackHeaders)addHeaderDict
addHeaderDict adds several headers to every request that this release item object sends afterwards.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: ReleaseItem. The same release item 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 release item 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 item 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 items = stack.release('<RELEASE_UID>').item().addHeaderDict({
branch: '<BRANCH>',
'x-request-id': 'docs-123'
})
console.log(items.stackHeaders)create
create adds one entry or asset, or a list of them, to a release.
| Name | Type | Description |
|---|---|---|
| param (required) | object | One item, or a list of items. |
| param.item | ReleaseItemData | One item to add. Pass item or items. |
| param.item.uid (required) | string | UID of the entry or asset. |
| param.item.version (required) | number | Version of the entry or asset. |
| param.item.locale (required) | string | Locale code of the item. |
| param.item.content_type_uid (required) | string | Content type UID, or built_io_upload for an asset. |
| param.item.action (required) | string | publish or unpublish. |
| param.items | ReleaseItemData[] | Items to add, with the fields of item. |
| param.release_version | string | Release version header, for example 2.0. |
Returns: Promise<Release>. The updated release.
Known issue After a call with a single item, this ReleaseItem keeps the /item path, so later findAll, move and delete calls on the same object go to the wrong endpoint and fail. Call release.item() again for each request.
Validation
- There is no client-side validation. The SDK sends param as you pass it.
- Calling create() with no argument returns a promise that rejects with TypeError, because create reads properties of param.
- 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
- With param.item, one call sends one Add a single item to a Release request (POST /v3/releases/{release_uid}/item).
- Without param.item, one call sends one Add multiple items to a Release request (POST /v3/releases/{release_uid}/items).
- The SDK sends the whole param object as the JSON body. A release_version value goes as the release_version header and also stays in the body.
- create resolves to a new Release that the SDK builds from the release key of the response, with the headers of the stack.
Example
Basic usage: add one entry to 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('<RELEASE_UID>').item().create({
item: { uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }
})
console.log(release.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: add an entry and an asset with the release version header
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>').item().create({
items: [
{ uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' },
{ uid: '<ASSET_UID>', version: 1, locale: '<LOCALE>', content_type_uid: 'built_io_upload', action: 'publish' }
],
release_version: '2.0'
})
console.log(release.uid)
} catch (error) { console.error(error.errorMessage) }delete
delete removes the items you list from a release, or every item when you list none.
| Name | Type | Description |
|---|---|---|
| params (required) | object | Items to remove, or {} for every item. |
| params.items | ReleaseItemData[] | Items to remove. |
| params.item | ReleaseItemData | One item to remove. |
| params.release_version | string | Release version header, for example 2.0. |
Returns: Promise<Response>. The API response with a notice.
Warning delete({}) removes every item from the release. The entries and assets stay in the stack, but you need to add them to the release again with the create method.
Known issue delete() with no argument returns a promise that rejects with TypeError instead of removing every item. Pass {} to remove every item.
Known issue After a call with a single item, this ReleaseItem keeps the /item path, so later findAll, move and delete calls on the same object go to the wrong endpoint and fail. Call release.item() again for each request.
Validation
- There is no client-side validation. The SDK sends the items as you pass them.
- 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
- The request depends on which key params holds:
- With items, one call sends one Delete multiple items from a Release request (DELETE /v3/releases/{release_uid}/items) with the body { "items": [...] }.
- With neither item nor items, the SDK adds the query parameter all=true and sends { "items": [] }, so the API removes every item.
- With item, the SDK sends the request to /v3/releases/{release_uid}/item with the body { "item": {...} }.
- The API reference documents the removal of one item at /items. To remove one item, pass a one-element items array.
- A release_version value goes as the release_version header and also stays in the body.
- delete resolves to the response body, which holds notice.
Example
Basic usage: remove one entry from 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>').item().delete({
items: [{ uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', 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: remove every item with the release version header
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
// No item or items key, so the SDK removes every item
const response = await stack.release('<RELEASE_UID>').item().delete({ release_version: '2.0' })
console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }Single item form: remove one item with the item key
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>').item().delete({
item: { uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }
})
console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }findAll
findAll lists the entries and assets in a release.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
| param.include_count | boolean | Adds the total number as count. |
| param.limit | number | Number of items to return. |
| param.skip | number | Number of items to skip. |
| param.include_branch | boolean | Adds the _branch key to the response. |
| param.release_version | string | Release version header, for example 2.0. |
Returns: Promise<ContentstackCollection>. The items of the release.
Validation
- There is no client-side validation.
- 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 all items in a Release request (GET /v3/releases/{release_uid}/items).
- The SDK sends param.release_version as the release_version header and removes it from the query. Every other key of param goes in the query string.
- findAll resolves to a ContentstackCollection. Its items are ReleaseItem objects with the item fields, and it holds count when the response has one.
- The SDK does not page through results. Use limit and skip to read the next page.
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.content_type_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: read a page of ten items with the total count
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({
include_count: true,
limit: 10,
skip: 0,
include_branch: true,
release_version: '2.0'
})
console.log(result.count, result.items.length)
} catch (error) { console.error(error.errorMessage) }move
move moves items from this release to the release that release_uid names.
| Name | Type | Description |
|---|---|---|
| options (required) | object | Request body and the release version. |
| options.param (required) | MoveReleaseItems | Request body with the target release and items. |
| options.param.release_uid (required) | string | UID of the release to move the items to. |
| options.param.items (required) | ReleaseItemData[] | Items to move. |
| options.release_version | string | Release version header, for example 2.0. |
Returns: Promise<Response>. The API response body.
Validation
- There is no client-side validation. The SDK sends options.param as you pass it.
- Calling move() with no argument returns a promise that rejects with TypeError, because move reads its options from one object.
- move reads the body only from options.param. Under any other key, such as data, the SDK sends the request with no body.
- 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 PUT /v3/releases/{release_uid}/items/move request with options.param as the JSON body.
- A non-empty options.release_version goes as the release_version header.
- move resolves to the response body. When the response has no body, it resolves to undefined.
Example
Basic usage: move one entry to another release
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const target = await stack.release().create({ release: { name: 'docs-test-summer-campaign' } })
const response = await stack.release('<RELEASE_UID>').item().move({
param: {
release_uid: target.uid,
items: [{ uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }]
}
})
console.log(response)
} 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: move an entry with the release version header
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const target = await stack.release().create({ release: { name: 'docs-test-summer-campaign' } })
const response = await stack.release('<RELEASE_UID>').item().move({
param: {
release_uid: target.uid,
items: [{ uid: '<ENTRY_UID>', version: 1, locale: '<LOCALE>', content_type_uid: '<CONTENT_TYPE_UID>', action: 'publish' }]
},
release_version: '2.0'
})
console.log(response)
} catch (error) { console.error(error.errorMessage) }removeHeader
removeHeader removes one header from the requests that this release item object sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: ReleaseItem. The same release item 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 release item 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 items = stack.release('<RELEASE_UID>').item().removeHeader('branch')
console.log(items.stackHeaders)