Stack
Stack
A Stack holds the API key of one stack and creates the objects that manage its content. Every stack-level request in the JavaScript Management SDK starts from it.
Use this class to
- open the modules of a stack, such as content types, assets, environments, tokens or releases
- fetch, update or delete one stack
- read and change the stack settings
- share the stack with a collaborator, change user roles, or transfer its ownership
- create a stack, or list every stack you can access
Instance State
Get a Stack from the stack method of the client. The form you get depends on whether you pass an API key.
- Call client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' }) to work with one stack, for example through contentType or fetch. Add branch_uid: '<BRANCH>' to send the branch header.
- Call client.stack(), or client.stack({ organization_uid: '<ORGANIZATION_UID>' }), to work with all your stacks through create and query.
The two forms have different methods. A method of the other form is undefined, so if you call it, the SDK throws TypeError. For example, client.stack().fetch() throws, and so does client.stack({ api_key: '<API_KEY>' }).create(...).
The Stack objects that fetch, update and create resolve to, and the items of a query result, are in the API key form.
Warning The SDK picks the form from the truthiness of api_key. An empty string or a missing api_key returns the client.stack() form without an error, and the mistake surfaces only when a method such as contentType is undefined. The same rule applies to the UID of every factory method: stack.contentType('') returns the collection form, like stack.contentType().
Class-Level Notes
Authentication for stack-level requests.
- The Content Management API (CMA) requires an authtoken for every request in the Manage the stack, Manage collaborators and ownership, and Create and list stacks groups below. Use contentstack.client({ authtoken: '<AUTHTOKEN>' }), or log in, then call client.stack({ api_key: '<API_KEY>' }).
- The modules you open with a factory method follow the authentication rules of their own API. Many accept a management token, for example content types and environments. Delivery and management token requests need an authtoken.
Each client stores one management token.
- client.stack({ management_token }) writes the token to the client's default authorization header, not to the stack. Every request of that client sends it, including the requests of stacks you open without a management token.
- A second client.stack({ management_token }) call with another token replaces the first for every stack of the client. Use a separate client per token, or set the token on one stack with addHeader.
Headers and branches.
- The stack keeps one header map, which contains api_key and, when you pass branch_uid, branch. Every request of the stack sends it.
- A module object from a factory method shares this map. A header you add to the stack later reaches module objects created before and after the change, until a module object changes its own headers. The globalField object is the exception: it copies the map when you create it.
- The Stack objects that fetch, update and create resolve to start a new map that contains only api_key. Keep using the stack from client.stack(...) for work on a branch.
Rate limiting and retry.
- This SDK retries a request that receives 429 automatically, with configurable delay and attempt limits.
Additional Resource For more information on the retry settings and their defaults, refer to the Contentstack documentation.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Send the Reset stack settings request | No | resetSettings sends the Add stack settings request with empty groups. Set each value with addSettings |
| Use two management tokens on one client | No | Create a separate client per token, or set the token on one stack with addHeader |
| Keep the branch header on a stack from fetch or update | No | Open modules from the stack that client.stack(...) returns |
| Accept a stack ownership invitation | No | The new owner opens the link in the invitation email |
Method Index
The method groups below follow the two forms in Instance State. Every group except Create and list stacks needs the API key form.
Open the content modules. Available on client.stack({ api_key }). These methods send no request. Call a request method on the object each method returns. The following table lists the methods.
| Method Name | Returns | Description |
|---|---|---|
| contentType | A new content type object. | Opens one content type, or all of them. |
| globalField | A new global field object. | Opens one global field, or all of them. |
| asset | A new asset object. | Opens one asset, or all of them. |
| taxonomy | A new taxonomy object. | Opens one taxonomy, or all of them. |
| variantGroup | A new variant group object. | Opens one variant group, or all of them. |
| variants | A new variant object. | Opens one variant, or all of them. |
| locale | A new locale object. | Opens one language, or all of them. |
| label | A new label object. | Opens one label, or all of them. |
| extension | A new extension object. | Opens one extension, or all of them. |
Open the publishing modules. Available on client.stack({ api_key }). These methods send no request, and the following table lists them.
| Method Name | Returns | Description |
|---|---|---|
| environment | A new environment object. | Opens one environment, or all of them. |
| release | A new release object. | Opens one release, or all of them. |
| bulkOperation | A new bulk operation object. | Opens bulk publish, unpublish and delete. |
| workflow | A new workflow object. | Opens one workflow, or all of them. |
| webhook | A new webhook object. | Opens one webhook, or all of them. |
Open the access, branch and audit modules. Available on client.stack({ api_key }). These methods send no request.
| Method Name | Returns | Description |
|---|---|---|
| deliveryToken | A new delivery token object. | Opens one delivery token, or all of them. |
| managementToken | A new management token object. | Opens one management token, or all of them. |
| role | A new role object. | Opens one role, or all of them. |
| branch | A new branch object. | Opens one branch, or all of them. |
| branchAlias | A new branch alias object. | Opens one branch alias, or all of them. |
| auditLog | A new audit log object. | Opens one audit log item, or the whole log. |
Manage the stack. Available on client.stack({ api_key }), from a client with an authtoken. The following table lists the stack methods and what each one does.
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested stack. | Fetches the details of the stack. |
| update | The updated stack. | Saves a new name and description. |
| delete | The API response with a notice. | Deletes the stack permanently. |
| settings | The stack settings. | Fetches the stack settings. |
| addSettings | The updated stack settings. | Adds or changes stack settings. |
| resetSettings | The stack settings after the request. | Sends empty settings groups. |
Manage collaborators and ownership. Available on client.stack({ api_key }), from a client with an authtoken.
| Method Name | Returns | Description |
|---|---|---|
| users | The users who collaborate on the stack. | Lists the stack collaborators. |
| share | The API response with a notice. | Invites users to the stack with roles. |
| unShare | The API response with a notice. | Removes a user from the stack. |
| updateUsersRoles | The API response with a notice. | Replaces the roles of users. |
| transferOwnership | The API response with a notice. | Invites a user to take ownership. |
Create and list stacks. Available on client.stack() and client.stack({ organization_uid }), from a client with an authtoken.
| Method Name | Returns | Description |
|---|---|---|
| create | The new stack. | Creates a stack in an organization. |
| query | A query for stacks, sent when you call find(), findOne() or count(). | Lists the stacks you can access. |
Set headers. Available on both forms. The following table lists the header methods.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same stack, for chaining. | Adds one header to the stack. |
| addHeaderDict | The same stack, for chaining. | Adds several headers to the stack. |
| removeHeader | The same stack, for chaining. | Removes one header from the stack. |
Class-Level Snippet
The snippet below opens a stack with a management token, lists its content types, and prints their UIDs.
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().query().find()
result.items.forEach((contentType) => console.log(contentType.uid))
} 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 Stack class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one request header to the stack, for the stack's own requests and for the module objects that share its header map.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header, for example organization_uid. |
| value (required) | string | Value to send in the header. |
Returns: Stack. The same stack, for chaining.
Validation
- There is no client-side validation of the header name or value. addHeader ignores a null or undefined key and returns the stack unchanged.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeader writes the pair into the stack's header map and sends no request.
- Every later request of the stack sends the map. A module object from a factory method, such as contentType or deliveryToken, shares the same map. The header reaches module objects that you created before the call and after it.
- The two objects below keep their own copy of the map and do not receive the header:
- A module object on which you already called addHeader, addHeaderDict or removeHeader.
- A globalField object, which copies the map when you create it.
- A second call with the same key replaces the value. This includes the api_key and branch headers that client.stack(...) sets.
- The management token that client.stack({ management_token }) sets lives in the client's defaults, not in this map. addHeader('authorization', '<MANAGEMENT_TOKEN>') sends a different token for this stack's requests, and the map value wins over the client default.
- On client.stack(), the map starts empty, and create and query send what you add.
Example
Basic usage: send the organization UID for a single sign-on (SSO) organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' }).addHeader('organization_uid', '<ORGANIZATION_UID>')
console.log(stack.stackHeaders)Send a management token for one stack only
import contentstack from '@contentstack/management'
const client = contentstack.client()
// The token goes in this stack's header map, not in the client defaults
const stack = client.stack({ api_key: '<API_KEY>' }).addHeader('authorization', '<MANAGEMENT_TOKEN>')
console.log(stack.stackHeaders)addHeaderDict
addHeaderDict adds several request headers to the stack at once, for the stack's own requests and for the module objects that share its header map.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: Stack. The same stack, for chaining.
Validation
- There is no client-side validation of the header names or values. addHeaderDict ignores null, undefined and any value that is not an object, and returns the stack unchanged.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeaderDict copies every key of headerDict into the stack's header map and sends no request.
- A key that already exists takes the new value, including api_key and branch.
- The headers reach the same objects as addHeader does: the stack's own requests and every module object that still shares the stack's map.
Example
Basic usage: add two headers to the stack
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' }).addHeaderDict({
'x-request-id': 'docs-123',
'x-team': 'web'
})
console.log(stack.stackHeaders)addSettings
addSettings adds settings to the stack or changes existing ones, such as stack variables and rich text editor options. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| stackVariables | AnyProperty | Stack variables, or setting groups by name. |
| stackVariables.stack_variables | object | Stack variables, for example enforce_unique_urls. |
| stackVariables.live_preview | object | Live Preview settings of the stack. |
| stackVariables.rte | object | Rich text editor settings of the stack. |
Returns: Promise<object>. The updated stack settings.
Validation
- There is no client-side validation of the setting names or values.
- addSettings(null) rejects with TypeError before any request, because addSettings checks the keys of the object with the in operator. Pass an object.
- addSettings exists only on a stack opened with an API key. On client.stack() 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 one Add stack settings request (POST /stacks/settings) with the stack's headers.
- addSettings builds the body in one of two ways, by the keys of stackVariables:
- When stackVariables has a stack_variables, live_preview or rte key, the body is { stack_settings: stackVariables }, sent unchanged.
- Otherwise the SDK reads the whole object as stack variables, and the body is { stack_settings: { stack_variables: stackVariables } }.
- Because of the first rule, mixing the two shapes moves your stack variables. In { enforce_unique_urls: true, rte: { ... } }, enforce_unique_urls lands at the top of stack_settings, not inside stack_variables. Put stack variables under stack_variables whenever you also pass a group.
- The API reference lists stack variables such as the two below:
- enforce_unique_urls: keeps entry URLs unique across the stack.
- sys_rte_allowed_tags: takes a combination of figure, style and script.
- Resolves to the stack_settings object of the response, not to the whole body.
Example
Basic usage: add stack variables directly
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
// No group key, so the SDK sends this object as stack_variables
const stackSettings = await stack.addSettings({ enforce_unique_urls: true })
console.log(stackSettings.stack_variables)
} 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: send stack variables, Live Preview and rich text editor settings together
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const stackSettings = await stack.addSettings({
stack_variables: {
enforce_unique_urls: true,
sys_rte_allowed_tags: 'figure,style,script'
},
live_preview: {
enabled: true
},
rte: {
cs_only_breakline: true
}
})
console.log(stackSettings)
} catch (error) {
console.error(error.errorMessage)
}asset
asset creates a Asset object for one asset, or for all the assets of the stack. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| assetUid | string | UID of the asset to open. |
Returns: Asset. A new asset object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one asset, such as fetch, exist only on the object from asset('<ASSET_UID>'). On asset() they are undefined, and calling one 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. asset sends no request.
- With a UID, the object has fetch, replace and publish, for example. Without one, it has create, query and folder. The Asset page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one asset by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const asset = await stack.asset('<ASSET_UID>').fetch()
console.log(asset.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every asset of the 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.asset().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}auditLog
auditLog creates a AuditLog object for one audit log item, or for all the audit log items of the stack. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| logItemUid | string | UID of the log item to open. |
Returns: AuditLog. A new audit log object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one audit log item, such as fetch, exist only on the object from auditLog('<LOG_ITEM_UID>'). On auditLog() they are undefined, and calling one 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. auditLog sends no request.
- With a UID, the object has fetch, for example. Without one, it has fetchAll. The AuditLog page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one audit log item by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const logItem = await stack.auditLog('<LOG_ITEM_UID>').fetch()
console.log(logItem.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List the audit log of the 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.auditLog().fetchAll()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}branch
branch creates a Branch object for one branch, or for all the branches of the stack. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| branchUid | string | UID of the branch to open. |
Returns: Branch. A new branch object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one branch, such as fetch, exist only on the object from branch('<BRANCH>'). On branch() they are undefined, and calling one 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. branch sends no request.
- With a UID, the object has fetch, delete and compare, for example. Without one, it has create, query and merge. The Branch page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one branch by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const branch = await stack.branch('<BRANCH>').fetch()
console.log(branch.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every branch of the 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.branch().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}branchAlias
branchAlias creates a BranchAlias object for one branch alias, or for all the branch aliases of the stack. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| branchUid | string | UID of the branch alias to open. |
Returns: BranchAlias. A new branch alias object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one branch alias, such as fetch, exist only on the object from branchAlias('<ALIAS_UID>'). On branchAlias() they are undefined, and calling one 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. branchAlias sends no request.
- With a UID, the object has fetch, createOrUpdate and delete, for example. Without one, it has fetchAll. The BranchAlias page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one branch alias by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const branchAlias = await stack.branchAlias('<ALIAS_UID>').fetch()
console.log(branchAlias.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every branch alias of the 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.branchAlias().fetchAll()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}bulkOperation
bulkOperation creates a BulkOperation object that publishes, unpublishes or deletes many entries and assets in one request.
This method takes no parameters.
Returns: BulkOperation. A new bulk operation object.
Validation
- There is no client-side validation.
- 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. bulkOperation sends no request.
- The object has publish, unpublish, delete and jobStatus, for example. The BulkOperation page lists every method.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: check 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 status = await stack.bulkOperation().jobStatus({ job_id: '<JOB_UID>' })
console.log(status)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}contentType
contentType creates a ContentType object for one content type, or for all the content types of the stack.
| Name | Type | Description |
|---|---|---|
| contentTypeUid | string | UID of the content type to open. |
Returns: ContentType. A new content type object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one content type, such as fetch, exist only on the object from contentType('<CONTENT_TYPE_UID>'). On contentType() they are undefined, and calling one 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. contentType sends no request.
- With a UID, the object has fetch, update and entry, for example. Without one, it has create and query. The ContentType page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one content type by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const contentType = await stack.contentType('<CONTENT_TYPE_UID>').fetch()
console.log(contentType.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every content type of the 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.contentType().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}create
create creates a new stack in an organization.
| Name | Type | Description |
|---|---|---|
| data (required) | StackDetails | Details of the new stack, under a stack key. |
| data.stack.name (required) | string | Name of the new stack. |
| data.stack.master_locale (required) | string | Code of the master language, for example en-us. |
| data.stack.description | string | Description of the new stack. |
| param | object | Query parameters for the request. The API lists none. |
Returns: Promise<Stack>. The new stack.
Validation
- There is no client-side validation. create sends data unchanged as the body.
- create exists only on the collection form, client.stack() or client.stack({ organization_uid: '<ORGANIZATION_UID>' }). On a stack opened with an API key it is undefined, and calling it throws TypeError.
- The API rejects the request when the collection has no organization_uid, because Create stack requires the organization_uid header. Open the collection with client.stack({ organization_uid: '<ORGANIZATION_UID>' }).
- 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 one Create stack request (POST /stacks) with data as the body.
- create sends the organization_uid from client.stack({ organization_uid }) as a header. When param has an organization_uid key, the SDK sends it in the query string, not as a header.
- An organization can create only one stack per minute, as the API reference states.
- Resolves to a new Stack that carries the new stack's API key. It has the methods of a stack opened with client.stack({ api_key }), such as fetch and contentType, and sends only the api_key header.
Example
Basic usage: create a stack in an organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const stack = await client.stack({ organization_uid: '<ORGANIZATION_UID>' }).create({
stack: {
name: 'docs-test-stack',
master_locale: 'en-us'
}
})
console.log(stack.api_key)
} 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 stack with a description
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const stack = await client.stack({ organization_uid: '<ORGANIZATION_UID>' }).create(
{
stack: {
name: 'docs-test-marketing-stack',
description: 'Content for the marketing website',
master_locale: 'en-us'
}
},
{}
)
console.log(stack.api_key, stack.name)
} catch (error) {
console.error(error.errorMessage)
}delete
delete permanently deletes the stack and all of its content.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. The API lists none. |
Returns: Promise<Response>. The API response with a notice.
Warning delete removes the stack permanently, with its content types, entries, assets and settings. You cannot undo it or restore the stack.
Validation
- There is no client-side validation.
- delete exists only on a stack opened with an API key. On client.stack() 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 one Delete stack request (DELETE /stacks) with the stack's headers. The api_key header selects the stack.
- Resolves to the response body, which carries notice.
Example
Basic usage: delete a stack
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const response = await stack.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)
}deliveryToken
deliveryToken creates a DeliveryToken object for one delivery token, or for all the delivery tokens of the stack. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| deliveryTokenUid | string | UID of the delivery token to open. |
Returns: DeliveryToken. A new delivery token object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one delivery token, such as fetch, exist only on the object from deliveryToken('<TOKEN_UID>'). On deliveryToken() they are undefined, and calling one 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. deliveryToken sends no request.
- With a UID, the object has fetch, update and previewToken, for example. Without one, it has create and query. The DeliveryToken page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
- The delivery token requests need an authtoken, so the examples below log in with one. The DeliveryToken page explains why.
Example
Basic usage: fetch one delivery token by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const deliveryToken = await stack.deliveryToken('<TOKEN_UID>').fetch()
console.log(deliveryToken.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every delivery token of the stack
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const result = await stack.deliveryToken().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}environment
environment creates a Environment object for one environment, or for all the environments of the stack.
| Name | Type | Description |
|---|---|---|
| environmentUid | string | Name of the environment to open. |
Returns: Environment. A new environment object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one environment, such as fetch, exist only on the object from environment('<ENVIRONMENT>'). On environment() they are undefined, and calling one 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. environment sends no request.
- With a UID, the object has fetch, update and delete, for example. Without one, it has create and query. The Environment page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one environment by its name
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const environment = await stack.environment('<ENVIRONMENT>').fetch()
console.log(environment.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every environment of the 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.environment().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}extension
extension creates a Extension object for one extension, or for all the extensions of the stack.
| Name | Type | Description |
|---|---|---|
| extensionUid | string | UID of the extension to open. |
Returns: Extension. A new extension object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one extension, such as fetch, exist only on the object from extension('<EXTENSION_UID>'). On extension() they are undefined, and calling one 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. extension sends no request.
- With a UID, the object has fetch, update and delete, for example. Without one, it has create, upload and query. The Extension page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one extension by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const extension = await stack.extension('<EXTENSION_UID>').fetch()
console.log(extension.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every extension of the 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.extension().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}fetch
fetch retrieves the details of the stack, such as its name, owner and master language.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
| param.include_collaborators | boolean | Includes the stack collaborators in the response. |
| param.include_stack_variables | boolean | Includes the stack variables in the response. |
| param.include_discrete_variables | boolean | Includes the stack access token in the response. |
Returns: Promise<Stack>. The requested stack.
Validation
- There is no client-side validation.
- fetch exists only on a stack opened with an API key, such as client.stack({ api_key: '<API_KEY>' }). On client.stack() 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 one Get a single stack request (GET /stacks) with the stack's headers, and every key of param as a query parameter.
- For a single sign-on (SSO) organization, the API requires the organization_uid header. Add it with addHeader before you call fetch.
- Resolves to a new Stack that the SDK builds from the stack key of the response. The properties of the response, such as name and master_locale, are properties of the new object.
- The new Stack sends only the api_key header. It does not keep the branch header from branch_uid, or any header that addHeader put on the original stack. Keep using the stack from client.stack(...) to open modules on a branch.
Example
Basic usage: fetch the stack details
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const stackDetails = await stack.fetch()
console.log(stackDetails.name, stackDetails.master_locale)
} 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: include the collaborators, stack variables and access token
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const stackDetails = await stack.fetch({
include_collaborators: true,
include_stack_variables: true,
include_discrete_variables: true
})
console.log(stackDetails.collaborators, stackDetails.stack_variables, stackDetails.discrete_variables)
} catch (error) {
console.error(error.errorMessage)
}globalField
globalField creates a GlobalField object for one global field, or for all the global fields of the stack, with an optional API version and branch.
| Name | Type | Description |
|---|---|---|
| uidOrOptions | string | object | UID of the global field, or the options object. |
| option | object | Options for every request of the object. |
| option.api_version | string | Value sent in the api_version header. |
| option.branch | string | Value sent in the branch header. |
Returns: GlobalField. A new global field object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one global field, such as fetch, exist only on the object from globalField('<GLOBAL_FIELD_UID>'). On globalField() they are undefined, and calling one 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. globalField sends no request.
- When uidOrOptions is an object, globalField reads it as option and returns the collection form. globalField({ api_version: '3.2' }) is the same as globalField(null, { api_version: '3.2' }).
- With a UID, the object has fetch, update and delete, for example. Without one, it has create, query and import. The GlobalField page lists every method of each form.
- Every request of the object sends the api_version and branch headers. When you pass no option.branch, the SDK uses the stack's branch header, then the client's default branch header, then 'main'.
- Unlike the other factory methods, globalField copies the stack's headers when you call it. A header you add to the stack later does not reach this object. Add the header before you call globalField, or call addHeader on the object.
Example
Basic usage: fetch one global field by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const globalField = await stack.globalField('<GLOBAL_FIELD_UID>').fetch()
console.log(globalField.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: fetch a global field from a branch with API version 3.2
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const globalField = await stack.globalField('<GLOBAL_FIELD_UID>', { api_version: '3.2', branch: '<BRANCH>' }).fetch()
console.log(globalField.title)
} catch (error) {
console.error(error.errorMessage)
}Pass the options object as the only argument to list every global field
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.globalField({ api_version: '3.2' }).query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}label
label creates a Label object for one label, or for all the labels of the stack.
| Name | Type | Description |
|---|---|---|
| labelUid | string | UID of the label to open. |
Returns: Label. A new label object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one label, such as fetch, exist only on the object from label('<LABEL_UID>'). On label() they are undefined, and calling one 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. label sends no request.
- With a UID, the object has fetch, update and delete, for example. Without one, it has create and query. The Label page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one label by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const label = await stack.label('<LABEL_UID>').fetch()
console.log(label.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every label of the 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.label().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}locale
locale creates a Locale object for one locale, or for all the locales of the stack.
| Name | Type | Description |
|---|---|---|
| code | string | Code of the language to open, for example fr-fr. |
Returns: Locale. A new locale object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one locale, such as fetch, exist only on the object from locale('<LOCALE>'). On locale() they are undefined, and calling one 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. locale sends no request.
- With a UID, the object has fetch, update and delete, for example. Without one, it has create and query. The Locale page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one language by its code
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const locale = await stack.locale('<LOCALE>').fetch()
console.log(locale.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every locale of the 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.locale().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}managementToken
managementToken creates a ManagementToken object for one management token, or for all the management tokens of the stack.
| Name | Type | Description |
|---|---|---|
| managementTokenUid | string | UID of the management token to open. |
Returns: ManagementToken. A new management token object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one management token, such as fetch, exist only on the object from managementToken('<TOKEN_UID>'). On managementToken() they are undefined, and calling one 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. managementToken sends no request.
- With a UID, the object has fetch, update and delete, for example. Without one, it has create and query. The ManagementToken page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
- The management token requests need an authtoken, so the examples below log in with one. The ManagementToken page explains why.
Example
Basic usage: fetch one management token by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const managementToken = await stack.managementToken('<TOKEN_UID>').fetch()
console.log(managementToken.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every management token of the stack
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const result = await stack.managementToken().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}query
query builds a query for all the stacks that you own or that other users share with you.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the request. |
| params.query | object | Filter conditions, sent as JSON in query. |
| params.include_collaborators | boolean | Includes the collaborators of each stack. |
| params.include_stack_variables | boolean | Includes the stack variables of each stack. |
| params.include_discrete_variables | boolean | Includes the access token of each stack. |
| params.include_count | boolean | Includes the total number of stacks as count. |
Returns: Query. A query for stacks, sent when you call find(), findOne() or count().
Validation
- There is no client-side validation.
- query exists only on the collection form, client.stack() or client.stack({ organization_uid: '<ORGANIZATION_UID>' }). On a stack opened with an API key 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 sends no request. The find, findOne and count methods of the returned Query send the Get all stacks request (GET /stacks).
- On client.stack({ organization_uid }), every request of the query sends the organization_uid header, which the API requires for a single sign-on (SSO) organization.
- On the same form, query also adds an org_uid condition to params.query. It writes into the params.query object you pass, so that object changes after the call.
- Each item in the items array of the find result is a Stack opened with that stack's API key. It has methods such as fetch and contentType, and sends only the api_key header.
Example
Basic usage: list the stacks of an organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const result = await client.stack({ organization_uid: '<ORGANIZATION_UID>' }).query().find()
result.items.forEach((stack) => console.log(stack.name, stack.api_key))
} 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: filter by name and include the details of each stack
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const result = await client.stack().query({
query: { name: 'Marketing site' },
include_collaborators: true,
include_stack_variables: true,
include_discrete_variables: true,
include_count: true
}).find()
console.log(result.count, result.items.length)
} catch (error) {
console.error(error.errorMessage)
}release
release creates a Release object for one release, or for all the releases of the stack.
| Name | Type | Description |
|---|---|---|
| releaseUid | string | UID of the release to open. |
Returns: Release. A new release object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one release, such as fetch, exist only on the object from release('<RELEASE_UID>'). On release() they are undefined, and calling one 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. release sends no request.
- With a UID, the object has fetch, item and deploy, for example. Without one, it has create and query. The Release page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one release by its UID
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.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every release of the 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()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}removeHeader
removeHeader removes one request header from the stack, for the stack's own requests and for the module objects that share its header map.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: Stack. The same stack, for chaining.
Validation
- There is no client-side validation. removeHeader ignores a null or undefined key and returns the stack unchanged.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. removeHeader deletes the key from the stack's header map and sends no request. A key that is not in the map changes nothing.
- The removal reaches the same objects as addHeader does: the stack's own requests and every module object that still shares the stack's map.
- removeHeader('branch') stops the stack and those module objects from sending the branch header.
- removeHeader('api_key') leaves the requests without the stack API key, and the API rejects them.
- The management token that client.stack({ management_token }) sets lives in the client's defaults, not in this map. removeHeader('authorization') does not remove it.
Example
Basic usage: stop sending 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>' })
stack.removeHeader('branch')
console.log(stack.stackHeaders)resetSettings
resetSettings sends empty stack_variables and discrete_variables groups to the stack settings.
This method takes no parameters.
Returns: Promise<object>. The stack settings after the request.
Warning Treat resetSettings as a change you cannot undo. Save the output of settings before you call it, so that you can restore values with addSettings.
Validation
- There is no client-side validation.
- resetSettings exists only on a stack opened with an API key. On client.stack() 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 one POST /stacks/settings request with the stack's headers, and { stack_settings: { discrete_variables: {}, stack_variables: {} } } as the body. That path belongs to the Add stack settings request.
- Known issue: In 1.32.0, resetSettings does not send the Reset stack settings request (POST /stacks/settings/reset). To set a stack variable to a known value, pass it to addSettings.
- Resolves to the stack_settings object of the response, not to the whole body.
Example
Basic usage: send empty settings groups and print the result
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const stackSettings = await stack.resetSettings()
console.log(stackSettings)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}role
role creates a Role object for one role, or for all the roles of the stack.
| Name | Type | Description |
|---|---|---|
| uid | string | UID of the role to open. |
Returns: Role. A new role object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one role, such as fetch, exist only on the object from role('<ROLE_UID>'). On role() they are undefined, and calling one 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. role sends no request.
- With a UID, the object has fetch, update and delete, for example. Without one, it has create, query and fetchAll. The Role page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one role by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const role = await stack.role('<ROLE_UID>').fetch()
console.log(role.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every role of the 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.role().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}settings
settings retrieves the configuration settings of the stack.
This method takes no parameters.
Returns: Promise<object>. The stack settings.
Validation
- There is no client-side validation.
- settings exists only on a stack opened with an API key. On client.stack() 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 one Get stack settings request (GET /stacks/settings) with the stack's headers.
- Resolves to the stack_settings object of the response, not to the whole body. The object holds groups such as stack_variables.
- When your organization has Disable Fallback Publishing turned on, the settings include disable_fallback_publish. When it is true, the API publishes an entry only in the locales where the entry has a localized version, as the API reference states.
Example
Basic usage: print the stack variables
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const stackSettings = await stack.settings()
console.log(stackSettings.stack_variables)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}share
share invites users to collaborate on the stack and assigns each of them roles.
| Name | Type | Description |
|---|---|---|
| emails | string[] | Email addresses of the users to invite. |
| roles | AnyProperty | Each email address mapped to an array of role UIDs. |
Returns: Promise<Response>. The API response with a notice.
Validation
- There is no client-side validation. share sends both arguments unchanged, so an email address in emails without an entry in roles reaches the API as it is.
- share exists only on a stack opened with an API key. On client.stack() 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 one Share a stack request (POST /stacks/share) with the stack's headers, and { emails, roles } as the body.
- Resolves to the response body, which carries notice.
- To remove a collaborator later, use the unShare method. To change the roles of a collaborator, use the updateUsersRoles method.
Example
Basic usage: invite a user with one role
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const response = await stack.share(
['<COLLABORATOR_EMAIL>'],
{ '<COLLABORATOR_EMAIL>': ['<ROLE_UID>'] }
)
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)
}taxonomy
taxonomy creates a Taxonomy object for one taxonomy, or for all the taxonomies of the stack.
| Name | Type | Description |
|---|---|---|
| taxonomyUid | string | UID of the taxonomy to open. |
Returns: Taxonomy. A new taxonomy object.
Validation
- There is no client-side validation. An empty string returns the collection form, which is also the default.
- Methods that act on one taxonomy, such as fetch, exist only on the object from taxonomy('<TAXONOMY_UID>'). On taxonomy() they are undefined, and calling one 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. taxonomy sends no request.
- With a UID, the object has fetch, update and terms, for example. Without one, it has create, query and import. The Taxonomy page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one taxonomy by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const taxonomy = await stack.taxonomy('<TAXONOMY_UID>').fetch()
console.log(taxonomy.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every taxonomy of the 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.taxonomy().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}transferOwnership
transferOwnership emails a user an invitation to take ownership of the stack.
| Name | Type | Description |
|---|---|---|
| email (required) | string | Email address of the new owner. |
Returns: Promise<Response>. The API response with a notice.
Warning When the user accepts the invitation, the ownership moves to them and you lose every permission on the stack, as the API reference states. You cannot take the ownership back yourself. The new owner has to transfer it to you.
Validation
- There is no client-side validation. Without email, the body is an empty JSON object {}, because JSON.stringify drops an undefined value.
- transferOwnership exists only on a stack opened with an API key. On client.stack() 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 one Transfer stack ownership to other users request (POST /stacks/transfer_ownership) with the stack's headers, and { transfer_to: email } as the body.
- The transfer completes only when the new owner opens the link in the invitation email. The SDK has no method that accepts the invitation.
- Resolves to the response body, which carries notice.
Example
Basic usage: invite a new owner
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const response = await stack.transferOwnership('<NEW_OWNER_EMAIL>')
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)
}unShare
unShare removes a user from the collaborators of the stack.
| Name | Type | Description |
|---|---|---|
| email (required) | string | Email address of the user to remove. |
Returns: Promise<Response>. The API response with a notice.
Warning After unShare, the user can no longer view the stack in their account, as the API reference states. To give the user access again, invite them with the share method and assign their roles again.
Validation
- There is no client-side validation. Without email, the body is an empty JSON object {}, because JSON.stringify drops an undefined value.
- unShare exists only on a stack opened with an API key. On client.stack() 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 one Unshare a stack request (POST /stacks/unshare) with the stack's headers, and { email } as the body.
- Resolves to the response body, which carries notice.
Example
Basic usage: remove a collaborator
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const response = await stack.unShare('<COLLABORATOR_EMAIL>')
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)
}update
update saves the name and description that you set on the stack object to the stack.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. The API lists none. |
Returns: Promise<Stack>. The updated stack.
Validation
- There is no client-side validation.
- update exists only on a stack opened with an API key. On client.stack() 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 one Update stack request (PUT /stacks) with the stack's headers.
- update builds the request body from the object's own properties, under a stack key. It leaves out api_key, uid, org_uid, the created_*, updated_* and deleted_at fields, and the methods. Set name and description on the object before you call update.
- On an object from fetch, the body also carries the other fetched properties, such as master_locale. The API does not change the master language after you create the stack.
- Resolves to a new Stack that the SDK builds from the response. Like the result of fetch, it sends only the api_key header.
Example
Basic usage: rename the stack
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const stackDetails = await stack.fetch()
stackDetails.name = 'Marketing site'
stackDetails.description = 'Content for the marketing website'
const updatedStack = await stackDetails.update()
console.log(updatedStack.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Update without fetching first
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
// The body holds only the properties set on this object
stack.name = 'Marketing site'
const updatedStack = await stack.update({})
console.log(updatedStack.name)
} catch (error) {
console.error(error.errorMessage)
}updateUsersRoles
updateUsersRoles replaces the roles of one or more users of the stack.
| Name | Type | Description |
|---|---|---|
| data (required) | AnyProperty | User UIDs mapped to arrays of role UIDs. |
Returns: Promise<Response>. The API response with a notice.
Warning The roles you pass replace every role the user has on the stack. The API removes every role that you leave out. To keep a role, include its UID in the array.
Validation
- There is no client-side validation. updateUsersRoles sends data unchanged.
- updateUsersRoles exists only on a stack opened with an API key. On client.stack() 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 one Update User Role request (POST /stacks/users/roles) with the stack's headers, and { users: data } as the body.
- Each key of data is a user UID, and its value is the array of role UIDs that the user gets. For example, a user with the Developer role who receives only the Content Manager role loses the Developer role, as the API reference states.
- Resolves to the response body, which carries notice.
Example
Basic usage: assign two roles to a user
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const response = await stack.updateUsersRoles({
'<USER_UID>': ['<ROLE_UID>', '<ROLE_UID>']
})
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)
}users
users retrieves the users who collaborate on the stack.
This method takes no parameters.
Returns: Promise<User[]>. The users who collaborate on the stack.
Validation
- There is no client-side validation.
- users exists only on a stack opened with an API key. On client.stack() 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 one Get a single stack request (GET /stacks) with include_collaborators=true and the stack's headers. It does not send the Get all users of a stack request (GET /stacks/users).
- Resolves to an array of User objects, one per entry in the collaborators array of the response. The array is empty when the response has no collaborators.
- The array is a plain JavaScript array, not a ContentstackCollection, so it has no items or count property.
Example
Basic usage: list the email address of each collaborator
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const users = await stack.users()
users.forEach((user) => console.log(user.email))
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}variantGroup
variantGroup creates a VariantGroup object for one variant group, or for all the variant groups of the stack.
| Name | Type | Description |
|---|---|---|
| variantGroupUid | string | UID of the variant group to open. |
Returns: VariantGroup. A new variant group object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one variant group, such as update, exist only on the object from variantGroup('<VARIANT_GROUP_UID>'). On variantGroup() they are undefined, and calling one 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. variantGroup sends no request.
- With a UID, the object has update, delete and variants, for example. Without one, it has create and query. The VariantGroup page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: list the variants of one variant group
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.variantGroup('<VARIANT_GROUP_UID>').variants().query().find()
console.log(result.items.length)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every variant group of the 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.variantGroup().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}variants
variants creates a Variants object for one variant, or for all the variants of the stack.
| Name | Type | Description |
|---|---|---|
| variantsUid | string | UID of the variant to open. |
Returns: Variants. A new variant object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one variant, such as fetch, exist only on the object from variants('<VARIANT_UID>'). On variants() they are undefined, and calling one 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 sends no request.
- With a UID, the object has fetch and delete, for example. Without one, it has create, query and fetchByUIDs. The Variants page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one variant by its UID
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.variants('<VARIANT_UID>').fetch()
console.log(variant.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every variant of the 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.variants().query().find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}webhook
webhook creates a Webhook object for one webhook, or for all the webhooks of the stack. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| webhookUid | string | UID of the webhook to open. |
Returns: Webhook. A new webhook object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one webhook, such as fetch, exist only on the object from webhook('<WEBHOOK_UID>'). On webhook() they are undefined, and calling one 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. webhook sends no request.
- With a UID, the object has fetch, update and executions, for example. Without one, it has create, fetchAll and import. The Webhook page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one webhook by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const webhook = await stack.webhook('<WEBHOOK_UID>').fetch()
console.log(webhook.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every webhook of the 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.webhook().fetchAll()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}workflow
workflow creates a Workflow object for one workflow, or for all the workflows of the stack.
| Name | Type | Description |
|---|---|---|
| workflowUid | string | UID of the workflow to open. |
Returns: Workflow. A new workflow object.
Validation
- There is no client-side validation. An empty string returns the collection form, as null does.
- Methods that act on one workflow, such as fetch, exist only on the object from workflow('<WORKFLOW_UID>'). On workflow() they are undefined, and calling one 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. workflow sends no request.
- With a UID, the object has fetch, update and enable, for example. Without one, it has create, fetchAll and publishRule. The Workflow page lists every method of each form.
- Each call returns a new object that shares the stack's header map, with api_key and, when set, branch. A header you add to the stack later also reaches this object, until you call addHeader, addHeaderDict or removeHeader on the object itself.
Example
Basic usage: fetch one workflow by its UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const workflow = await stack.workflow('<WORKFLOW_UID>').fetch()
console.log(workflow.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}List every workflow of the 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.workflow().fetchAll()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}