Labels
Labels
A label groups content types that work together, such as the content types of one website section. The Label class manages the labels of a stack through the Content Management API (CMA). Use this class to
- add a label and assign content types to it
- list the labels of a stack, or read one by its UID
- rename a label, nest it under a parent label, or change its content types
- delete a label
Call the label method of the Stack class to get an object.
Instance State
- Call stack.label() without a UID to work with the labels of the stack, for example create and query.
- Call stack.label('<LABEL_UID>') to work with one label, for example fetch and delete.
- Each form has only its own methods. A method of the other form is undefined, and calling it throws TypeError.
- The objects that create, fetch, update and query().find() return are the single-label form.
The Method Index below lists the full set for each form.
Warning stack.label('') 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
Branch scoping.
- When you create the stack with branch_uid, every request from this class sends the branch header, and the API works with the labels of that branch.
Headers.
- Every request sends the headers of this object. The object shares the header map of the stack until you change its headers with addHeader, addHeaderDict or removeHeader. The first change gives the object its own copy.
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
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Update fields without fetching first | No | update sends the properties of the object. Call fetch, change the result, then call update |
Method Index
Work with the labels of a stack. Available on stack.label().
| Method Name | Returns | Description |
|---|---|---|
| create | The new label. | Adds a label to the stack. |
| query | A query for labels, sent when you call find(), findOne() or count(). | Lists the labels of the stack. |
Work with one label. Available on stack.label('<LABEL_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested label. | Reads one label. |
| update | The updated label. | Saves changes to the label. |
| delete | The API response with a notice. | Deletes the label. |
Set request headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same label object, for chaining. | Adds one request header. |
| addHeaderDict | The same label object, for chaining. | Adds several request headers. |
| removeHeader | The same label object, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below adds a label for two content types, then lists 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 label = await stack.label().create({
label: { name: 'docs-test-blog', content_types: ['<CONTENT_TYPE_UID>', 'author'] }
})
console.log(label.uid)
const labels = await stack.label().query().find()
labels.items.forEach((item) => console.log(item.uid, item.name))
} 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 Label class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one header to every request that this label object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
Returns: Label. The same label 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.
- Until its first header change, this object shares the header map of the stack. The first change copies that map, so the header applies to this object only, not to the stack or to other objects of the same stack.
- Every request method of this object sends its headers. A key that the object already holds gets the new value.
- query copies the headers of this object when you call it. Add the header first, then call query.
Example
Basic usage: tag the requests of one label object
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const label = stack.label('<LABEL_UID>').addHeader('x-request-id', 'docs-123')
// Every request this object sends from now on carries the header
console.log(label.stackHeaders['x-request-id'])addHeaderDict
addHeaderDict adds several headers to every request that this label object sends.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: Label. The same label 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.
- Copies every key of headerDict into the headers of this object. A key that the object already holds gets the new value.
- The first header change on this object copies the header map that it shares with the stack. The change then applies to this object only.
Example
Basic usage: send two extra headers from one label object
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const label = stack.label('<LABEL_UID>').addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'docs-456' })
// fetch, update and delete on this object send both headers
console.log(label.stackHeaders)create
create adds a label to the stack and assigns content types to it.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Request body with the label under label. |
| data.label.name (required) | string | Name of the label. |
| data.label.content_types (required) | string[] | UIDs of the content types in the label. |
| data.label.parent | string[] | UID of the parent label. |
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
Returns: Promise<Label>. The new label.
Validation
- There is no client-side validation. create sends data as the JSON body as it is.
- create exists only on stack.label(). On stack.label('<LABEL_UID>') it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/labels with data as the body and every key of param as a query parameter, as Add label describes.
- Resolves to a new Label object that holds the created label, with fetch, update and delete. When the API answers with an empty body, it resolves to { status, statusText } instead.
Example
Basic usage: add a label for one content type
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().create({
label: { name: 'docs-test-blog', content_types: ['<CONTENT_TYPE_UID>'] }
})
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)
}All parameters: add a child label on a branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const label = await stack.label().create({
label: {
name: 'docs-test-blog-authors',
content_types: ['<CONTENT_TYPE_UID>'],
parent: ['<LABEL_UID>']
}
}, { include_branch: true })
console.log(label.uid, label.parent, label._branch)
} catch (error) {
console.error(error.errorMessage)
}delete
delete removes the label whose UID you passed to stack.label('<LABEL_UID>') from the stack.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
Returns: Promise<Response>. The API response with a notice.
Warning A successful delete removes the label permanently, and you cannot undo it.
Validation
- There is no client-side validation.
- delete exists only on stack.label('<LABEL_UID>') and on the Label objects that requests return. On stack.label() 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 DELETE /v3/labels/{label_uid} with every key of param as a query parameter, as Delete label describes. The API reference lists no query parameters for this request.
- Resolves to the response body, which carries notice. When the API answers with an empty body, it resolves to { status, statusText } instead.
Example
Basic usage: delete a label
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.label('<LABEL_UID>').delete()
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: 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 {
// delete sends every key of the object as a query parameter. The API lists none for this request.
const response = await stack.label('<LABEL_UID>').delete({})
console.log(response.notice)
} catch (error) {
console.error(error.errorMessage)
}fetch
fetch retrieves the label whose UID you passed to stack.label('<LABEL_UID>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
Returns: Promise<Label>. The requested label.
Validation
- There is no client-side validation.
- fetch exists only on stack.label('<LABEL_UID>') and on the Label objects that requests return. On stack.label() 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/labels/{label_uid} with every key of param as a query parameter, as Get a single label describes.
- Resolves to a new Label object that the SDK builds from the label key of the response, with fetch, update and delete.
Example
Basic usage: read one label
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.name, label.content_types)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: read a label of a branch with its branch UID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const label = await stack.label('<LABEL_UID>').fetch({ include_branch: true })
console.log(label.name, label._branch)
} catch (error) {
console.error(error.errorMessage)
}query
query builds a request that lists the labels of the stack. It sends nothing until you call find(), findOne() or count() on the result.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the list request. |
| params.query | object | Filter condition, sent as JSON, for example by name. |
| params.include_count | boolean | Adds the total label count to the response. |
| params.include_branch | boolean | Adds the _branch key to each item. |
Returns: Query. A query for labels, sent when you call find(), findOne() or count().
Validation
- There is no client-side validation.
- query exists only on stack.label(). On stack.label('<LABEL_UID>') it is undefined, and calling it throws TypeError.
- An invalid value surfaces as a rejected promise from the request method you call next.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- query sends no request. find(), findOne() and count() on the returned object each send GET /v3/labels, as Get all labels 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.
- The returned object copies the headers of this label object when you call query. A header that you add to the label object later does not reach it.
- find() resolves to a collection whose items are Label objects, each with fetch, update and delete. With include_count: true, the collection also has count. See the find method of the Query class for the collection.
Example
Basic usage: list the labels of a stack
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const result = await stack.label().query().find()
result.items.forEach((label) => console.log(label.uid, label.name))
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: find a label by name on a branch, 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>', branch_uid: '<BRANCH>' })
try {
const result = await stack.label()
.query({ query: { name: 'docs-test-blog' }, include_count: true, include_branch: true })
.find()
console.log(result.count, result.items.map((label) => label._branch))
} catch (error) {
console.error(error.errorMessage)
}removeHeader
removeHeader removes one header from the requests that this label object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: Label. The same label 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.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. removeHeader sends no request.
- Removing a header that the object shares with the stack first copies the shared map, so the stack and other objects keep the header.
- The SDK adds some headers at request time, for example the authorization header of the client. removeHeader cannot remove those.
Example
Basic usage: send requests from one label object without 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>' })
const label = stack.label('<LABEL_UID>').removeHeader('branch')
// This object now works with the default branch
console.log(label.stackHeaders.branch)update
update saves your changes to the properties of this label object, such as its name, parent or content types.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
Returns: Promise<Label>. The updated label.
Validation
- There is no client-side validation.
- update exists only on stack.label('<LABEL_UID>') and on the Label objects that requests return. On stack.label() 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 PUT /v3/labels/{label_uid} with every key of param as a query parameter, as Update label describes.
- The body is { label: { ... } }, built from the properties of this object. The SDK leaves out uid, created_at, created_by, updated_at, updated_by, deleted_at, org_uid, api_key and its own internal properties.
- Call fetch first and change the result. An object from stack.label('<LABEL_UID>') holds only the UID, so update on it sends an empty label object.
- Resolves to a new Label object that the SDK builds from the label key of the response.
Example
Basic usage: rename a label
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()
label.name = 'docs-test-articles'
const updated = await label.update()
console.log(updated.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: add a content type to a label on a branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const label = await stack.label('<LABEL_UID>').fetch()
label.content_types = [...label.content_types, '<CONTENT_TYPE_UID>']
const updated = await label.update({ include_branch: true })
console.log(updated.content_types, updated._branch)
} catch (error) {
console.error(error.errorMessage)
}