Branch

View as Markdown

Branch

A branch is an isolated copy of the content types, global fields and content of a stack. The Branch class manages branches through the Content Management API (CMA). Use this class to

  • list the branches of a stack, or read one branch
  • create a branch from a source branch, and choose the environments it clones
  • delete a branch
  • compare two branches, merge one branch into another, and check merge jobs

Call the branch method of the Stack class to get an object.

Instance State

  • Call stack.branch() without a UID to work with the collection, for example create and merge.
  • Call stack.branch('<BRANCH>') to work with one branch, for example fetch and compare.
  • Each form has only its own methods. A method of the other form is undefined, and calling it throws TypeError. For example, stack.branch('<BRANCH>').mergeQueue() throws, because mergeQueue exists only on stack.branch().

The Method Index below lists the full set for each form.

Warning stack.branch('') returns the collection form, because the SDK treats an empty string as no UID. Check the UID before you build the object.

Class-Level Notes

Authentication.

  • create and delete accept only an authtoken, as Create a branch and Delete a branch state. Create the client with contentstack.client({ authtoken: '<AUTHTOKEN>' }) and the stack with client.stack({ api_key: '<API_KEY>' }).
  • The other request methods accept a management token.

Branch objects from responses.

  • create, fetch and the find() call of query resolve to Branch objects in the one-branch form, with fetch, delete, compare and updateSettings. The branch details are properties of the object, for example uid, source and alias.

Headers.

  • Every request sends the headers of this object, which start as a copy of the stack headers. Change them with addHeader, addHeaderDict and removeHeader.
  • The Compare and MergeQueue objects start with the headers that this object holds when you call compare or mergeQueue. Set custom headers here, before that call.

Rate limiting and retry.

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

Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.

Capability Matrix

CapabilitySupportedNotes / Alternative
Create or delete a branch with a management tokenNoThe API accepts only an authtoken for these requests.
Rename a branch or change its sourceNoThe class has no update method. Create a new branch instead.
Wait until a new branch is availableNoRetry fetch with a delay until it succeeds.
Compare entries or assets between branchesNoThe API compares content types and global fields only. See the Compare class.

Method Index

Work with the branch collection. Available on stack.branch().

Method NameReturnsDescription
createThe new branch.Creates a branch from a source branch.
queryA query for branches, sent when you call find(), findOne() or count().Lists the branches of the stack.
mergeThe API response with the merge job details.Merges a compare branch into a base branch.
mergeQueueA new merge queue object.Returns an object for merge jobs.

Work with one branch. Available on stack.branch('<BRANCH>').

Method NameReturnsDescription
fetchThe requested branch.Reads one branch.
deleteThe API response with a notice.Deletes the branch and its content.
compareA new compare object.Returns an object that compares two branches.
updateSettingsThe API response with a notice.Updates the settings of the branch.

Set request headers. Available on both forms.

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

Class-Level Snippet

The snippet below lists the branches of a stack with a management token, then reads the first 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 branches = await stack.branch().query({ include_count: true }).find()
  console.log(branches.count)

  if (branches.items.length > 0) {
    const branch = await stack.branch(branches.items[0].uid).fetch()
    console.log(branch.uid, branch.source)
  }
} 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 Branch class has its own section below, with its parameters, validation rules, behavior, and examples.

addHeader

addHeader adds one header to the requests that this branch object sends.

NameTypeDescription
key (required)string

Header name, for example x-request-id.

Default: Not applicable
value (required)string

Header value to send.

Default: Not applicable

Returns: Branch. The same branch object, for chaining.

Validation

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

Behavior

  • Client-side only. addHeader sends no request.
  • The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
  • Every request method of this object sends its headers.
  • Objects that this branch object creates afterwards start with its headers. These include the Compare object from compare and the MergeQueue object from mergeQueue.
  • A key that the object already holds gets the new value.

Example

Basic usage: tag the requests of one branch object

import contentstack from '@contentstack/management'

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

const target = stack.branch('<BRANCH>').addHeader('x-request-id', 'docs-123')
console.log(target.stackHeaders['x-request-id'])

addHeaderDict

addHeaderDict adds several headers at once to the requests that this branch object sends.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: Branch. The same branch object, for chaining.

Validation

  • There is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeaderDict sends no request.
  • addHeaderDict copies every key of headerDict into the header map of this object. A key that the object already holds gets the new value.
  • The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
  • Every request method of this object sends its headers.
  • Objects that this branch object creates afterwards start with its headers. These include the Compare object from compare and the MergeQueue object from mergeQueue.

Example

Basic usage: add a request ID and a trace ID

import contentstack from '@contentstack/management'

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

const target = stack.branch('<BRANCH>').addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
console.log(target.stackHeaders['x-request-id'], target.stackHeaders['x-trace-id'])

compare

compare returns a Compare object that holds this branch as the base branch and the branch you name as the compare branch. The following table lists its parameters.

NameTypeDescription
compareBranchUid (required)string

UID of the branch to compare with this branch.

Default: Not applicable

Returns: Compare. A new compare object.

Validation

  • There is no client-side validation.
  • compare exists only on stack.branch('<BRANCH>'). On stack.branch() it is undefined, and calling it throws TypeError.
  • When you omit compareBranchUid, or pass an empty string, the Compare object sends neither base_branch nor compare_branch. The API then rejects the comparison, because it requires compare_branch.
  • 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

  • compare sends no request. It stores the UID of this branch as base_branch and compareBranchUid as compare_branch. The Compare object sends both as query parameters on every request.
  • The Compare object starts with the current headers of this branch object. To send a custom header with the comparison, add it to the branch object before you call compare.

Example

Basic usage: list the differences between main and another branch

import contentstack from '@contentstack/management'

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

try {
  // base_branch is main and compare_branch is the branch you pass
  const differences = await stack.branch('main').compare('<COMPARE_BRANCH>').all({ limit: 100 })
  console.log(JSON.stringify(differences))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

create

create creates a branch in the stack from the source branch you name, and can limit which environments the new branch clones.

NameTypeDescription
data (required){ branch: BranchData }

Request body, with the branch under the branch key.

Default: Not applicable
data.branch.uid (required)string

Sets the UID of the new branch.

Default: Not applicable
data.branch.source (required)string

Names the branch to copy, for example main.

Default: Not applicable
data.branch.publish_config.environmentsstring[]

Lists the environment names, not UIDs, to clone.

Default: API default (clones all environments)
paramobject

Query parameters, sent as given.

Default: undefined (sends no extra query parameters)

Returns: Promise<Branch>. The new branch.

Note The publish_config.environments option requires version 1.32.0 or later of the JavaScript Management SDK. Its TypeScript type is IBranchPublishConfig, which differs from the PublishConfig type that entry and asset publishing use.

Validation

  • There is no client-side validation. create sends data as given, including the environment list, and does not check the names or the list length.
  • create exists only on stack.branch(). On stack.branch('<BRANCH>') it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
  • The API rejects the request with 422 and creates no branch when an environment name in publish_config.environments does not exist in the stack, alone or mixed with valid names. The names match by exact case, so Development does not match an environment named development. The errors object of the error carries a publish_config.environments key.
  • The API also rejects a missing uid or source, and a uid that already exists in the stack.

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

Behavior

  • Sends POST /v3/stacks/branches with data as the JSON body and param as query parameters, as Create a branch describes. The API reference lists no query parameters for this request.
  • The API accepts only an authtoken for this request, not a management token. Create the client with authtoken, or call client.login() first.
  • The API clones environments into the new branch from the publish_config.environments list, in one of the following three ways:
    • A list of environment names clones only those environments.
    • An empty list ([]) clones no environments.
    • When you omit publish_config, the API clones all environments.
  • Resolves to a Branch object that the SDK builds from the branch key of the response, with fetch, delete, compare and updateSettings. When you sent publish_config.environments, the new branch carries the resolved list under publish_config.environments.
  • The new branch can take several seconds to become available after the promise resolves. Retry the fetch method with a delay until it succeeds before you work in the branch.

Example

Basic usage: create a branch from main

import contentstack from '@contentstack/management'

// Creating a branch needs an authtoken, not a management token
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const branch = await stack.branch().create({ branch: { uid: 'docs-test-dev', source: 'main' } })
  console.log(branch.uid, branch.source)
} 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 branch that clones only development and staging

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

// List the environments by name, not by UID
const data = {
  branch: {
    uid: 'docs-test-dev',
    source: 'main',
    publish_config: { environments: ['development', 'staging'] }
  }
}

try {
  // The second argument holds query parameters. The API lists none for this request.
  const branch = await stack.branch().create(data, {})
  console.log(branch.uid, branch.publish_config.environments)
} catch (error) {
  console.error(error.errorMessage)
}

Edge case: create a branch that clones no environments

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

// An empty list clones no environments. Omitting publish_config clones all of them.
const data = {
  branch: { uid: 'docs-test-dev', source: 'main', publish_config: { environments: [] } }
}

try {
  const branch = await stack.branch().create(data)
  console.log(branch.uid, branch.publish_config.environments) // []
} catch (error) {
  console.error(error.errorMessage)
}

Error handling: an environment name that does not exist

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

const data = {
  branch: {
    uid: 'docs-test-dev',
    source: 'main',
    publish_config: { environments: ['development', 'docs-test-missing-environment'] }
  }
}

try {
  await stack.branch().create(data)
} catch (error) {
  // 422: one name does not exist in the stack, and the API creates no branch
  console.error(error.status, error.errorMessage, error.errors['publish_config.environments'])
}

delete

delete deletes the branch whose UID you passed to stack.branch('<BRANCH>'), with all the content in it.

NameTypeDescription
paramobject

Query parameters, sent with force=true.

Default: {}

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

Warning Deleting a branch removes the branch and all the content in it permanently, and also deletes the alias that points to it. You cannot undo this.

Validation

  • There is no client-side validation.
  • delete exists only on stack.branch('<BRANCH>'). On stack.branch() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
  • The API rejects the request when another branch uses this branch as its source. Delete the child branches first.

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

Behavior

  • Sends DELETE /v3/stacks/branches/{branch_uid} with every key of param as a query parameter, as Delete a branch describes.
  • delete always adds force=true to the query parameters, which the API requires to confirm the deletion. You do not need to pass it.
  • The API accepts only an authtoken for this request, not a management token. Create the client with authtoken, or call client.login() first.
  • Resolves to the response body as a plain object, with the API message in notice.

Example

Basic usage: delete a branch

import contentstack from '@contentstack/management'

// Deleting a branch needs an authtoken, not a management token
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const response = await stack.branch('<BRANCH>').delete()
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: pass query parameters

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  // The SDK sends force=true on every delete, so passing it changes nothing
  const response = await stack.branch('<BRANCH>').delete({ force: true })
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

fetch

fetch retrieves the branch whose UID you passed to stack.branch('<BRANCH>').

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

Returns: Promise<Branch>. The requested branch.

Validation

  • There is no client-side validation.
  • fetch exists only on stack.branch('<BRANCH>'). On stack.branch() 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 GET /v3/stacks/branches/{branch_uid} with every key of param as a query parameter, as Get a single branch describes. The API reference lists no query parameters for this request.
  • Resolves to a new Branch object that the SDK builds from the branch key of the response, with fetch, delete, compare and updateSettings. The branch details, such as uid, source and alias, are properties of the object.
  • A new branch from create can take several seconds to become available. Until then, fetch rejects. Retry with a delay.

Example

Basic usage: read one branch

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, branch.source, branch.alias)
} 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: pass query parameters

import contentstack from '@contentstack/management'

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

try {
  // fetch sends every key of the object as a query parameter. The API lists none for this request.
  const branch = await stack.branch('<BRANCH>').fetch({})
  console.log(branch.uid)
} catch (error) {
  console.error(error.errorMessage)
}

Edge case: wait until a new branch is available

import contentstack from '@contentstack/management'

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

let branch = null
for (let attempt = 0; attempt < 10 && !branch; attempt++) {
  try {
    branch = await stack.branch('<BRANCH>').fetch()
  } catch (error) {
    console.error(error.errorMessage)
    // Wait two seconds before the next attempt
    await new Promise((resolve) => setTimeout(resolve, 2000))
  }
}
console.log(branch ? branch.uid : 'The branch is not available yet.')

merge

merge merges the changes of a compare branch into a base branch, with the merge strategy you choose.

NameTypeDescription
mergeObj (required)IMergeObj

Request body. Pass {} to set no item strategies.

Default: Not applicable
mergeObj.item_merge_strategiesIMergeStrategy[]

Per-item strategies that override the default strategy.

Default: API default
mergeObj.item_merge_strategies[].uid (required)string

UID of the content type or global field.

Default: Not applicable
mergeObj.item_merge_strategies[].type (required)string

content_type or global_field.

Default: Not applicable
mergeObj.item_merge_strategies[].merge_strategy (required)MergeStrategy

Strategy for this item.

Default: Not applicable
params (required)IMergeParams

Query parameters that describe the merge.

Default: Not applicable
params.base_branchstring

Branch that receives the changes.

Default: API default
params.compare_branch (required)string

Branch whose changes you merge.

Default: Not applicable
params.default_merge_strategy (required)MergeStrategy

Strategy for every item without its own strategy.

Default: Not applicable
params.merge_comment (required)string

Comment shown for the merge.

Default: Not applicable
params.no_revertboolean

The SDK sends it as the no_revert query parameter.

Default: API default

Returns: Promise<Response>. The API response with the merge job details.

Validation

  • There is no client-side validation. merge sends mergeObj and params as given.
  • merge exists only on stack.branch(). On stack.branch('<BRANCH>') it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
  • The API rejects a merge when compare_branch, default_merge_strategy or merge_comment is missing, because the API reference marks all three as required.

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

Behavior

  • Sends POST /v3/stacks/branches_merge with mergeObj as the JSON body and every key of params as a query parameter, as Merge branches describes.
  • MergeStrategy accepts the following seven values: merge_prefer_base, merge_prefer_compare, overwrite_with_compare, merge_new_only, merge_modified_only_prefer_base, merge_modified_only_prefer_compare and ignore.
  • To merge only some items, set default_merge_strategy to ignore and list those items in item_merge_strategies.
  • Resolves to the response body as a plain object, not to a Branch object.
  • The API runs the merge as a job. Check its status with the mergeQueue method.

Example

Basic usage: merge a development branch into main

import contentstack from '@contentstack/management'

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

const params = {
  base_branch: 'main',
  compare_branch: '<COMPARE_BRANCH>',
  default_merge_strategy: 'merge_prefer_base',
  merge_comment: 'Merge the redesign into main'
}

try {
  const response = await stack.branch().merge({}, params)
  console.log(JSON.stringify(response))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: merge one global field and ignore everything else

import contentstack from '@contentstack/management'

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

const mergeObj = {
  item_merge_strategies: [
    { uid: '<GLOBAL_FIELD_UID>', type: 'global_field', merge_strategy: 'merge_prefer_compare' }
  ]
}
const params = {
  base_branch: 'main',
  compare_branch: '<COMPARE_BRANCH>',
  default_merge_strategy: 'ignore',
  merge_comment: 'Merge the SEO global field only',
  no_revert: true
}

try {
  const response = await stack.branch().merge(mergeObj, params)
  console.log(JSON.stringify(response))
} catch (error) {
  console.error(error.errorMessage)
}

mergeQueue

mergeQueue returns a MergeQueue object that lists the recent merge jobs of the stack, or reads one merge job.

NameTypeDescription
uidstring

UID of one merge job to read.

Default: undefined (returns the list form, with find)

Returns: MergeQueue. A new merge queue object.

Validation

  • There is no client-side validation.
  • mergeQueue exists only on stack.branch(). On stack.branch('<BRANCH>') it is undefined, and calling it throws TypeError.
  • An empty string counts as no UID, so mergeQueue('') returns the list form, which has find and no fetch.
  • 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

  • mergeQueue sends no request.
  • Without a UID, the MergeQueue object has find, which lists the recent merge jobs.
  • With a UID, the object has fetch, which reads the status and configuration of that merge job.
  • The MergeQueue object starts with the current headers of this branch object. To send a custom header with the merge queue requests, add it to the branch object before you call mergeQueue.

Example

Basic usage: list the recent merge jobs, then read one

import contentstack from '@contentstack/management'

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

try {
  const jobs = await stack.branch().mergeQueue().find()
  console.log(JSON.stringify(jobs))

  const job = await stack.branch().mergeQueue('<MERGE_JOB_UID>').fetch()
  console.log(JSON.stringify(job))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

query

query builds a request that lists the branches of the stack. It sends nothing until you call find(), findOne() or count() on the result.

NameTypeDescription
paramsobject

Query parameters for the list request.

Default: {}
params.limitnumber

Maximum number of branches to return.

Default: API default
params.skipnumber

Number of branches to skip.

Default: API default
params.include_countboolean

Adds the total branch count to the response.

Default: API default
params.queryobject

Filter condition, sent as JSON.

Default: API default

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

Validation

  • There is no client-side validation.
  • query exists only on stack.branch(). On stack.branch('<BRANCH>') it is undefined, and calling it throws TypeError.
  • An invalid value surfaces as a rejected promise from the request method you call next.

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

Behavior

  • query sends no request. find(), findOne() and count() on the returned object each send GET /v3/stacks/branches, as Get all branches describes.
  • The SDK sends params.query as a JSON string in the query parameter, and every other key of params as its own query parameter.
  • find() resolves to a collection whose items are Branch objects, each with fetch, delete, compare and updateSettings. With include_count: true, the collection also has count.
  • The client does not page through results. Use limit and skip to read more pages.
  • See the Query class for find(), findOne() and count().

Example

Basic usage: list the branches of a stack

import contentstack from '@contentstack/management'

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

try {
  const branches = await stack.branch().query().find()
  for (const branch of branches.items) {
    console.log(branch.uid, branch.source)
  }
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: read the second page of branches whose source is main, with the total count

import contentstack from '@contentstack/management'

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

try {
  const branches = await stack.branch()
    .query({ limit: 10, skip: 10, include_count: true, query: { source: 'main' } })
    .find()
  console.log(branches.count, branches.items.map((branch) => branch.uid))
} catch (error) {
  console.error(error.errorMessage)
}

removeHeader

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

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: Branch. The same branch object, for chaining.

Validation

  • There is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged, and removeHeader returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. removeHeader sends no request.
  • The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
  • Every request method of this object sends its headers.
  • Objects that this branch object creates afterwards start with its headers. These include the Compare object from compare and the MergeQueue object from mergeQueue.
  • removeHeader can remove a header that the object inherited from the stack, such as branch. The stack and its other objects keep that header.
  • Do not remove api_key. Without it, the API cannot tell which stack the request is for.

Example

Basic usage: drop a header that you added earlier

import contentstack from '@contentstack/management'

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

const target = stack.branch('<BRANCH>')
  .addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
  .removeHeader('x-trace-id')
console.log('x-trace-id' in target.stackHeaders) // false

updateSettings

updateSettings updates the settings of the branch whose UID you passed to stack.branch('<BRANCH>'), such as the asset workspaces linked to it.

NameTypeDescription
payload (required)IBranchSettings

Request body, with the settings under branch.settings.

Default: Not applicable
payload.branch.settings.am_v2.linked_workspaces (required)ILinkedWorkspace[]

Asset workspaces to link to the branch.

Default: Not applicable
payload.branch.settings.am_v2.linked_workspaces[].uid (required)string

UID of the workspace.

Default: Not applicable
payload.branch.settings.am_v2.linked_workspaces[].space_uid (required)string

UID of the space that holds the workspace.

Default: Not applicable
payload.branch.settings.am_v2.linked_workspaces[].is_default (required)boolean

Marks the default workspace of the branch.

Default: Not applicable

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

Note updateSettings requires version 1.29.0 or later of the JavaScript Management SDK.

Validation

  • There is no client-side validation. updateSettings sends payload as given and does not check its keys.
  • updateSettings exists only on stack.branch('<BRANCH>'). On stack.branch() 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 POST /v3/stacks/branches/{branch_uid}/settings with payload as the JSON body and no query parameters.
  • The SDK does not wrap payload. Put the settings under branch.settings yourself.
  • The ILinkedWorkspace type also declares an optional operation string. The SDK sends it as given when you add it to a workspace entry.
  • Resolves to the response body as a plain object, with the API message in notice. It does not return a Branch object.

Example

Basic usage: link a default asset workspace to a branch

import contentstack from '@contentstack/management'

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

const payload = {
  branch: {
    settings: {
      am_v2: {
        linked_workspaces: [
          { uid: 'main', space_uid: '<SPACE_UID>', is_default: true }
        ]
      }
    }
  }
}

try {
  const response = await stack.branch('<BRANCH>').updateSettings(payload)
  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)
}