Stack

View as Markdown

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

CapabilitySupportedNotes / Alternative
Send the Reset stack settings requestNoresetSettings sends the Add stack settings request with empty groups. Set each value with addSettings
Use two management tokens on one clientNoCreate a separate client per token, or set the token on one stack with addHeader
Keep the branch header on a stack from fetch or updateNoOpen modules from the stack that client.stack(...) returns
Accept a stack ownership invitationNoThe 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 NameReturnsDescription
contentTypeA new content type object.Opens one content type, or all of them.
globalFieldA new global field object.Opens one global field, or all of them.
assetA new asset object.Opens one asset, or all of them.
taxonomyA new taxonomy object.Opens one taxonomy, or all of them.
variantGroupA new variant group object.Opens one variant group, or all of them.
variantsA new variant object.Opens one variant, or all of them.
localeA new locale object.Opens one language, or all of them.
labelA new label object.Opens one label, or all of them.
extensionA 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 NameReturnsDescription
environmentA new environment object.Opens one environment, or all of them.
releaseA new release object.Opens one release, or all of them.
bulkOperationA new bulk operation object.Opens bulk publish, unpublish and delete.
workflowA new workflow object.Opens one workflow, or all of them.
webhookA 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 NameReturnsDescription
deliveryTokenA new delivery token object.Opens one delivery token, or all of them.
managementTokenA new management token object.Opens one management token, or all of them.
roleA new role object.Opens one role, or all of them.
branchA new branch object.Opens one branch, or all of them.
branchAliasA new branch alias object.Opens one branch alias, or all of them.
auditLogA 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 NameReturnsDescription
fetchThe requested stack.Fetches the details of the stack.
updateThe updated stack.Saves a new name and description.
deleteThe API response with a notice.Deletes the stack permanently.
settingsThe stack settings.Fetches the stack settings.
addSettingsThe updated stack settings.Adds or changes stack settings.
resetSettingsThe 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 NameReturnsDescription
usersThe users who collaborate on the stack.Lists the stack collaborators.
shareThe API response with a notice.Invites users to the stack with roles.
unShareThe API response with a notice.Removes a user from the stack.
updateUsersRolesThe API response with a notice.Replaces the roles of users.
transferOwnershipThe 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 NameReturnsDescription
createThe new stack.Creates a stack in an organization.
queryA 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 NameReturnsDescription
addHeaderThe same stack, for chaining.Adds one header to the stack.
addHeaderDictThe same stack, for chaining.Adds several headers to the stack.
removeHeaderThe 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.

NameTypeDescription
key (required)string

Name of the header, for example organization_uid.

Default: Not applicable
value (required)string

Value to send in the header.

Default: Not applicable

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.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

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.

NameTypeDescription
stackVariablesAnyProperty

Stack variables, or setting groups by name.

Default: {}
stackVariables.stack_variablesobject

Stack variables, for example enforce_unique_urls.

Default: undefined
stackVariables.live_previewobject

Live Preview settings of the stack.

Default: undefined
stackVariables.rteobject

Rich text editor settings of the stack.

Default: undefined

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.

NameTypeDescription
assetUidstring

UID of the asset to open.

Default: null (returns the collection form)

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.

NameTypeDescription
logItemUidstring

UID of the log item to open.

Default: null (returns the collection form)

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.

NameTypeDescription
branchUidstring

UID of the branch to open.

Default: null (returns the collection form)

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.

NameTypeDescription
branchUidstring

UID of the branch alias to open.

Default: null (returns the collection form)

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.

NameTypeDescription
contentTypeUidstring

UID of the content type to open.

Default: null (returns the collection form)

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.

NameTypeDescription
data (required)StackDetails

Details of the new stack, under a stack key.

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

Name of the new stack.

Default: Not applicable
data.stack.master_locale (required)string

Code of the master language, for example en-us.

Default: Not applicable
data.stack.descriptionstring

Description of the new stack.

Default: undefined
paramobject

Query parameters for the request. The API lists none.

Default: undefined (sends no query parameters)

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request. The API lists none.

Default: {} (sends no query parameters)

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.

NameTypeDescription
deliveryTokenUidstring

UID of the delivery token to open.

Default: null (returns the collection form)

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.

NameTypeDescription
environmentUidstring

Name of the environment to open.

Default: null (returns the collection form)

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.

NameTypeDescription
extensionUidstring

UID of the extension to open.

Default: null (returns the collection form)

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {} (sends no query parameters)
param.include_collaboratorsboolean

Includes the stack collaborators in the response.

Default: API default
param.include_stack_variablesboolean

Includes the stack variables in the response.

Default: API default
param.include_discrete_variablesboolean

Includes the stack access token in the response.

Default: API default

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.

NameTypeDescription
uidOrOptionsstring | object

UID of the global field, or the options object.

Default: null (returns the collection form)
optionobject

Options for every request of the object.

Default: {}
option.api_versionstring

Value sent in the api_version header.

Default: '3.0'
option.branchstring

Value sent in the branch header.

Default: The stack's branch header, else 'main'

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.

NameTypeDescription
labelUidstring

UID of the label to open.

Default: null (returns the collection form)

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.

NameTypeDescription
codestring

Code of the language to open, for example fr-fr.

Default: null (returns the collection form)

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.

NameTypeDescription
managementTokenUidstring

UID of the management token to open.

Default: null (returns the collection form)

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.

NameTypeDescription
paramsobject

Query parameters for the request.

Default: {}
params.queryobject

Filter conditions, sent as JSON in query.

Default: undefined
params.include_collaboratorsboolean

Includes the collaborators of each stack.

Default: API default
params.include_stack_variablesboolean

Includes the stack variables of each stack.

Default: API default
params.include_discrete_variablesboolean

Includes the access token of each stack.

Default: API default
params.include_countboolean

Includes the total number of stacks as count.

Default: API default

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.

NameTypeDescription
releaseUidstring

UID of the release to open.

Default: null (returns the collection form)

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.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

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.

NameTypeDescription
uidstring

UID of the role to open.

Default: null (returns the collection form)

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.

NameTypeDescription
emailsstring[]

Email addresses of the users to invite.

Default: Empty array
rolesAnyProperty

Each email address mapped to an array of role UIDs.

Default: {}

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.

NameTypeDescription
taxonomyUidstring

UID of the taxonomy to open.

Default: '' (returns the collection form)

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.

NameTypeDescription
email (required)string

Email address of the new owner.

Default: Not applicable

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.

NameTypeDescription
email (required)string

Email address of the user to remove.

Default: Not applicable

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request. The API lists none.

Default: {} (sends no query parameters)

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.

NameTypeDescription
data (required)AnyProperty

User UIDs mapped to arrays of role UIDs.

Default: Not applicable

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.

NameTypeDescription
variantGroupUidstring

UID of the variant group to open.

Default: null (returns the collection form)

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.

NameTypeDescription
variantsUidstring

UID of the variant to open.

Default: null (returns the collection form)

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.

NameTypeDescription
webhookUidstring

UID of the webhook to open.

Default: null (returns the collection form)

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.

NameTypeDescription
workflowUidstring

UID of the workflow to open.

Default: null (returns the collection form)

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)
}