Asset
Asset
An asset is a file, such as an image, video, PDF or audio file, that you upload to a stack and use in entries. Use the Asset class to do the following tasks:
- upload a file from a path or a Buffer, replace the file, or change its title and description
- query the assets in a stack
- publish, unpublish or delete an asset
- list the entries and content types that reference an asset
- download the file of an asset
- open the Folder class for asset folder requests
The asset method on Stack returns a new Asset and sends no request.
Additional Resource The Assets section of the Content Management API (CMA) reference describes every asset request and its response.
Instance State
The form you call decides which methods the object has:
- Call stack.asset() without a UID to work on the collection (create, query).
- Call stack.asset('<ASSET_UID>') to work on one asset (fetch, publish).
- download and the three header methods exist on both forms.
The Method Index below lists the full set for each form. A method of the other form is undefined on the object, and calling it throws TypeError.
Warning stack.asset(''), stack.asset(null) and stack.asset(undefined) return the collection form, because the SDK treats an empty UID as no UID. Nothing fails at that point. The fetch call that follows throws TypeError. Check that the UID variable is non-empty before you call stack.asset.
Class-Level Notes
Requests and responses.
- Every request method is async and sends one request when you call it. stack.asset() and folder send no request.
- create, replace, fetch and update resolve to a new Asset that the SDK builds from the response. The asset fields, such as uid, title, filename, url and file_size, become properties of that object.
- Each object in the items array of a find result is an instance-form Asset, so you can call publish or download on it.
Uploads use form data.
- create and replace send a multipart/form-data body. The upload value is a file path or a Buffer.
- update sends a JSON body that the SDK builds from the properties of the object.
Headers and branches.
- stack.asset() gives the new object the headers of the stack, such as api_key and branch. addHeader changes only this object.
- Pass branch_uid to client.stack() to scope every asset request to one branch.
Rate limiting and retry.
- This SDK retries 429 automatically, with configurable delay and attempt limits.
Additional Resource The Contentstack class covers the retry options of contentstack.client() and their defaults.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Upload from a readable stream | No | upload accepts a file path or a Buffer. Read the stream into a Buffer first |
| Name asset versions or list asset versions | No | The SDK has no asset version methods. Send the Asset Versions requests of the CMA with your own HTTP client |
| Publish many assets in one request | No | Use the publish method of BulkOperation |
| Receive a Blob from download in Node.js | No | In Node.js, responseType: 'blob' returns a string. Use arraybuffer or stream |
Method Index
The first group works on stack.asset(). The second group works on stack.asset('<ASSET_UID>'). The last two groups work on both forms.
Upload and query assets. The methods in the table below are available on stack.asset().
| Method Name | Returns | Description |
|---|---|---|
| create | The new asset. | Uploads a file as a new asset. |
| query | A query for assets, sent when you call find(), findOne() or count(). | Builds a query for the assets of the stack. |
| folder | A new folder object. | Returns a Folder for folder requests. |
Work with one asset. The methods in the table below are available on stack.asset('<ASSET_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested asset. | Retrieves one asset. |
| update | The updated asset. | Saves the title, description and other changed properties. |
| replace | The asset with its new file. | Replaces the file of an asset. |
| getReferences | The entries and content types that reference the asset. | Lists where the asset is in use. |
| publish | The API response with the publish notice. | Publishes the asset. |
| unpublish | The API response with the unpublish notice. | Unpublishes the asset. |
| delete | The API response with a notice. | Deletes the asset. |
Download a file. The method in the table below is available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| download | The HTTP response with the file in data. | Downloads the file of an asset. |
Set request headers. The methods in the table below are available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same asset, for chaining. | Adds one request header. |
| addHeaderDict | The same asset, for chaining. | Adds several request headers. |
| removeHeader | The same asset, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below uploads an image into a folder and then publishes the new asset on one environment and locale.
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().create({
upload: '<FILE_PATH>',
title: 'docs-test-hero-image',
parent_uid: '<FOLDER_UID>'
})
const response = await asset.publish({
publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'] }
})
console.log(asset.uid, 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)
}Methods
Each method of the Asset class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one header to every request that this asset object sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the request header. |
| value (required) | string | Value of the request header. |
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation of the name or the value.
- A null or undefined key leaves the headers unchanged, and addHeader returns the object without an error.
- An invalid header surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeader stores the header on this asset object and sends no request.
- The first header method call on this object copies the headers it received from the stack, so the change applies to this asset object only. The stack and other objects keep their headers.
- Every later request from this object sends the header. A key that already exists, such as branch, takes the new value.
- Objects you create from this object afterwards start with its headers. For example, the Folder from the folder method of stack.asset() gets them.
Example
Basic usage: send this object's requests to another branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const asset = stack.asset('<ASSET_UID>').addHeader('branch', '<BRANCH>')
console.log(asset.stackHeaders)addHeaderDict
addHeaderDict adds several headers to every request that this asset object sends afterwards.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation of the names or the values.
- A headerDict that is null, undefined or not an object leaves the headers unchanged, and addHeaderDict returns the object without an error.
- An invalid header surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeaderDict copies each key and value of headerDict into the headers of this asset object and sends no request.
- The first header method call on this object copies the headers it received from the stack, so the change applies to this asset object only. The stack and other objects keep their headers.
- A key that already exists, such as branch, takes the new value.
- Objects you create from this object afterwards start with its headers. For example, the Folder from the folder method of stack.asset() gets them.
Example
Basic usage: add a branch and a request ID in one call
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const asset = stack.asset('<ASSET_UID>').addHeaderDict({
branch: '<BRANCH>',
'x-request-id': 'docs-123'
})
console.log(asset.stackHeaders)create
create uploads a file from a path or a Buffer and creates a new asset from it.
| Name | Type | Description |
|---|---|---|
| data (required) | AssetData | Form fields and the file to upload. |
| data.upload (required) | string | Buffer | Path of the file, or its bytes. |
| data.filename | string | File name sent with a Buffer upload. |
| data.content_type | string | MIME type of the file. |
| data.title | string | Title of the asset. |
| data.description | string | Description of the asset. |
| data.tags | string[] | string | Tags. The SDK joins an array with commas. |
| data.parent_uid | string | UID of the folder for the asset. |
| params | AnyProperty | Query parameters for the request. |
| params.relative_urls | boolean | Returns a relative URL in url. |
| params.include_dimension | boolean | Adds the image height and width. |
Returns: Promise<Asset>. The new asset.
Validation
- create checks only the type of data.upload. The returned promise rejects with an Error before any request when data.upload is neither a string nor a Buffer, because the request needs a file.
- When no file exists at the path, the returned promise rejects with an Error whose code is ENOENT. The SDK opens the file only when it sends the request.
- create exists only on stack.asset(). On stack.asset('<ASSET_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
- One call sends one Upload asset request (POST /v3/assets) with a multipart/form-data body and params as query parameters.
- The SDK sends each field as asset[<name>], for example asset[upload], asset[title] and asset[parent_uid].
- The SDK adds title, description and parent_uid only when the value is a string. It leaves out a value of any other type and raises no error.
- With a file path, the SDK names the file after the path and reads the MIME type from the extension, for example image/png for hero.png. data.content_type overrides it.
- With a Buffer, the SDK uses data.filename and data.content_type, or uploaded_file and application/octet-stream when you omit them.
- The SDK reads the file when it sends the request, and again for each retry.
- create resolves to a new Asset that the SDK builds from the asset key of the response.
Example
Basic usage: upload a file from a path
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().create({ upload: '<FILE_PATH>', title: 'docs-test-hero-image' })
console.log(asset.uid, asset.url)
} 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: upload a Buffer into a folder with tags
import { readFile } from 'node:fs/promises'
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const bytes = await readFile('<FILE_PATH>')
const asset = await stack.asset().create(
{
upload: bytes,
filename: 'docs-test-hero.png',
content_type: 'image/png',
title: 'docs-test-hero-image',
description: 'Hero image for the spring campaign',
tags: ['campaign', 'homepage'],
parent_uid: '<FOLDER_UID>'
},
{ relative_urls: true, include_dimension: true }
)
console.log(asset.uid, asset.url)
} catch (error) { console.error(error.errorMessage) }Edge case: an upload value that is neither a path nor a Buffer
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
// A number is not a path or a Buffer, so the SDK rejects before any request
await stack.asset().create({ upload: 42, title: 'docs-test-invalid' })
} catch (error) {
console.error(error.message)
}delete
delete deletes an asset from the stack.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
Returns: Promise<Response>. The API response with a notice.
Warning delete removes the asset and its file from the stack, and the SDK has no method that restores it.
Validation
- There is no client-side validation.
- delete exists only on stack.asset('<ASSET_UID>'). On stack.asset() 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
- One call sends one Delete asset request (DELETE /v3/assets/{asset_uid}) with param as query parameters. The API reference lists no query parameters for this request.
- delete resolves to the response body, which holds notice. When the response has no body, it resolves to { status, statusText }.
- To check where the asset is in use before you delete it, call the getReferences method.
Example
Basic usage: delete an asset
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.asset('<ASSET_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: delete an asset and 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 {
const response = await stack.asset('<ASSET_UID>').delete({ include_branch: true })
console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }download
download downloads the file of an asset from its URL and resolves to the HTTP response. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| options (required) | object | URL, response type and extra headers. |
| options.url | string | File URL. Required on stack.asset(). |
| options.responseType | AssetResponseType | Format of data, such as arraybuffer or stream. |
| options.params | object | Extra request headers, not query parameters. |
Returns: Promise<AxiosResponse>. The HTTP response with the file in data.
Validation
- The returned promise rejects with an Error before any request when neither options.url nor the url property of the asset holds a URL, because the request needs one. On stack.asset('<ASSET_UID>'), the url property exists only after fetch.
- Calling download() with no argument returns a promise that rejects with TypeError, because download reads its options from one object.
- When the file host rejects the request, the promise rejects with the axios error (AxiosError), not the SDK error. It carries status and response, and no errorMessage or errorCode.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one GET request to the URL. The URL is absolute, so the request goes to the file host, not to the Content Management API host.
- The request carries the headers of this object, such as api_key and branch, and the authorization header of the client. Each key of options.params becomes one more header.
- Pass only Contentstack asset URLs, so that these credentials do not reach another host.
- download resolves to the full axios response, with status, statusText, headers and data.
- In Node.js, responseType decides what data holds:
- arraybuffer gives a Buffer.
- stream gives a readable stream.
- blob, or no responseType, gives a string, which corrupts a binary file. Use blob only in a browser.
Example
Basic usage: fetch an asset and save its file
import { writeFile } from 'node:fs/promises'
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()
const response = await asset.download({ responseType: 'arraybuffer' })
await writeFile(asset.filename, response.data)
console.log(response.status, asset.filename)
} catch (error) {
// fetch rejects with the SDK error. download rejects with the axios error. Both carry status.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: stream a file from a known URL to disk
import { createWriteStream } from 'node:fs'
import { pipeline } from 'node:stream/promises'
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()
const response = await stack.asset().download({
url: asset.url,
responseType: 'stream',
// Each key becomes a request header
params: { 'x-request-id': 'docs-123' }
})
await pipeline(response.data, createWriteStream('<FILE_PATH>'))
} catch (error) { console.error(error.status, error.message) }fetch
fetch retrieves one asset, with its file details, from the stack.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
| param.version | number | Asset version to retrieve. |
| param.include_path | boolean | Adds the path of the parent folders. |
| param.environment | string | Returns the asset as published on this environment. |
| param.include_publish_details | boolean | Adds the publish details of the asset. |
| param.relative_urls | boolean | Returns a relative URL in url. |
| param.include_metadata | boolean | Adds the asset metadata under _metadata. |
| param.include_branch | boolean | Adds the _branch key to the asset. |
Returns: Promise<Asset>. The requested asset.
Validation
- There is no client-side validation.
- fetch exists only on stack.asset('<ASSET_UID>'). On stack.asset() 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
- One call sends one Get an asset request (GET /v3/assets/{asset_uid}) with param as query parameters and the headers of this object.
- fetch resolves to a new Asset that the SDK builds from the asset key of the response. The object you call fetch on keeps its old properties.
- The new object has the single-asset methods, so you can call update, publish or download on it.
Example
Basic usage: retrieve an asset by 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.title, asset.url)
} 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: retrieve version 2 as published on one environment
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({
version: 2,
include_path: true,
environment: '<ENVIRONMENT>',
include_publish_details: true,
relative_urls: true,
include_metadata: true,
include_branch: true
})
console.log(asset.title, asset.publish_details, asset.path)
} catch (error) { console.error(error.errorMessage) }folder
folder returns a new Folder object for asset folder requests and sends no request.
| Name | Type | Description |
|---|---|---|
| folderUid | string | UID of the folder. Omit it to create folders. |
Returns: Folder. A new folder object.
Validation
- There is no client-side validation.
- folder exists only on stack.asset(). On stack.asset('<ASSET_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
- folder('<FOLDER_UID>') returns a folder with fetch, update and delete.
- folder() returns a folder with create.
- An empty string or null returns the create form, because the SDK treats an empty UID as no UID.
- The new Folder starts with the headers of this asset object, such as api_key and branch.
Example
Basic usage: fetch one folder
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const folder = await stack.asset().folder('<FOLDER_UID>').fetch()
console.log(folder.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Collection form: create a folder
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const folder = await stack.asset().folder().create({ asset: { name: 'docs-test-folder' } })
console.log(folder.uid)
} catch (error) { console.error(error.errorMessage) }getReferences
getReferences lists the entries and content types that reference an asset.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
| param.include_publish_details | boolean | Adds the publish details of the asset. |
| param.include_branch | boolean | Adds the _branch key to the response. |
Returns: Promise<object>. The entries and content types that reference the asset.
Validation
- There is no client-side validation.
- getReferences exists only on stack.asset('<ASSET_UID>'). On stack.asset() 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
- One call sends one Get asset references request (GET /v3/assets/{asset_uid}/references) with param as query parameters.
- getReferences resolves to the response body as a plain object, not an Asset. The API reference describes its keys.
- With include_publish_details, the API adds the latest version number, the version name and the publish details of the asset.
Example
Basic usage: list where an asset is in use
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const references = await stack.asset('<ASSET_UID>').getReferences()
console.log(JSON.stringify(references, null, 2))
} 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 publish details and the branch key
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const references = await stack.asset('<ASSET_UID>').getReferences({
include_publish_details: true,
include_branch: true
})
console.log(JSON.stringify(references, null, 2))
} catch (error) { console.error(error.errorMessage) }publish
publish publishes an asset on the environments and locales you name, now or at a scheduled time.
| Name | Type | Description |
|---|---|---|
| options (required) | PublishConfig | Targets and request options. |
| options.publishDetails (required) | PublishDetails | Target environments and locales. |
| options.publishDetails.environments (required) | string[] | Environment names to publish on. |
| options.publishDetails.locales (required) | string[] | Locale codes to publish on. |
| options.locale | string | Locale sent as the top-level locale key. |
| options.version | number | Asset version to publish. |
| options.scheduledAt | string | ISO 8601 date and time to publish later. |
| options.headers | Record<string, string> | Extra headers for this request only. |
| options.params | Record<string, unknown> | Query parameters for this request. |
Returns: Promise<Response>. The API response with the publish notice.
Validation
- There is no client-side validation of the targets. The SDK sends publishDetails as you pass it.
- Calling publish() with no argument returns a promise that rejects with TypeError, because publish reads its options from one object.
- publish exists only on stack.asset('<ASSET_UID>'). On stack.asset() 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
- One call sends one Publish an asset request (POST /v3/assets/{asset_uid}/publish).
- The SDK builds the JSON body as { "asset": publishDetails } and adds locale, version and scheduled_at when you set them. It renames scheduledAt to scheduled_at.
- options.headers merge over the headers of this object for this request only. options.params go in the query string.
- Without scheduledAt, the API publishes the asset now. With it, the API schedules the publish for that time, for example 2026-12-01T09:00:00.000Z.
- The API publishes the metadata of the asset together with the asset.
- publish resolves to the response body, which holds notice. It does not return the asset.
Example
Basic usage: publish an asset on one environment now
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.asset('<ASSET_UID>').publish({
publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'] }
})
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: schedule a publish of version 2 on another branch
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.asset('<ASSET_UID>').publish({
publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'] },
locale: '<LOCALE>',
version: 2,
scheduledAt: '2026-12-01T09:00:00.000Z',
headers: { branch: '<BRANCH>' },
params: { include_branch: true }
})
console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }query
query builds a query for the assets of the stack. It sends no request until you call find(), findOne() or count().
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the request. |
| params.query | object | Filter, sent as query=<JSON>. |
| params.folder | string | Folder UID, or cs_root for the root folder. |
| params.include_folders | boolean | Adds folders to the results. |
| params.include_count | boolean | Adds the total number as count. |
| params.environment | string | Returns assets published on this environment. |
| params.include_publish_details | boolean | Adds the publish details of each asset. |
| params.relative_urls | boolean | Returns relative URLs in url. |
| params.asc | string | Field UID to sort by, ascending. |
| params.desc | string | Field UID to sort by, descending. |
| params.include_branch | boolean | Adds the _branch key to each asset. |
Returns: Query. A query for assets, sent when you call find(), findOne() or count().
Validation
- There is no client-side validation.
- query exists only on stack.asset(). On stack.asset('<ASSET_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 copies the headers of this object and params into a new Query object and sends nothing.
- find sends one Get all assets request (GET /v3/assets). It resolves to a ContentstackCollection whose items are Asset objects with the single-asset methods.
- With include_folders, each folder in the result also becomes an Asset object in items. Folders carry is_dir: true.
- The SDK does not page through results. Pass limit and skip in params to read the next page.
Example
Basic usage: list the assets of one folder
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({ folder: '<FOLDER_UID>' }).find()
result.items.forEach((asset) => console.log(asset.uid, asset.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: filter, sort and count the assets of the root folder
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({
query: { content_type: 'image/png' },
folder: 'cs_root',
include_folders: true,
include_count: true,
environment: '<ENVIRONMENT>',
include_publish_details: true,
relative_urls: true,
desc: 'updated_at',
include_branch: true
}).find()
console.log(result.count)
result.items.forEach((item) => console.log(item.is_dir ? 'folder' : 'asset', item.uid))
} catch (error) { console.error(error.errorMessage) }Edge case: sort ascending and read only the first match
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
// findOne sets limit=1. A query without a match resolves to an empty items array.
const result = await stack.asset().query({ query: { filename: 'hero.png' }, asc: 'created_at' }).findOne()
console.log(result.items.length ? result.items[0].uid : 'No match')
} catch (error) { console.error(error.errorMessage) }removeHeader
removeHeader removes one header from the requests that this asset object sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: Asset. The same asset, for chaining.
Validation
- There is no client-side validation.
- A null or undefined key, or a key that the object does not hold, leaves the headers unchanged, and removeHeader returns the object without an error.
- Removing api_key makes the next request fail with an API error, because every stack request needs the API key.
Behavior
- Client-side only. removeHeader deletes the header from this asset object and sends no request.
- When the header came from the stack, the SDK first copies the headers, so the stack and other objects keep it.
- The management token and the authtoken live on the client, not on this object. removeHeader('authorization') does not remove them.
Example
Basic usage: stop sending the branch header from one object
import contentstack from '@contentstack/management'
const client = contentstack.client()
// This stack sends a branch header on every request
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
const asset = stack.asset('<ASSET_UID>').removeHeader('branch')
console.log(asset.stackHeaders)replace
replace uploads a new file in place of the current file of an asset and keeps the asset UID. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| data (required) | AssetData | Form fields and the new file. |
| data.upload (required) | string | Buffer | Path of the new file, or its bytes. |
| data.filename | string | File name sent with a Buffer upload. |
| data.content_type | string | MIME type of the file. |
| data.title | string | New title of the asset. |
| data.description | string | New description of the asset. |
| data.tags | string[] | string | Tags. The SDK joins an array with commas. |
| data.parent_uid | string | UID of the folder for the asset. |
| params | AnyProperty | Query parameters for the request. |
| params.relative_urls | boolean | Returns a relative URL in url. |
Returns: Promise<Asset>. The asset with its new file.
Validation
- replace checks only the type of data.upload. The returned promise rejects with an Error before any request when data.upload is neither a string nor a Buffer, because the request needs a file.
- When no file exists at the path, the returned promise rejects with an Error whose code is ENOENT. The SDK opens the file only when it sends the request.
- replace exists only on stack.asset('<ASSET_UID>'). On stack.asset() 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
- One call sends one Replace asset request (PUT /v3/assets/{asset_uid}) with a multipart/form-data body and params as query parameters.
- replace builds the form the same way as the create method. Each field goes as asset[<name>]. The SDK adds title, description and parent_uid only when the value is a string.
- With a file path, the SDK reads the MIME type from the extension. With a Buffer, it uses data.filename and data.content_type, or uploaded_file and application/octet-stream.
- replace resolves to a new Asset that the SDK builds from the response. The asset keeps its UID.
Example
Basic usage: replace the file of an asset from a path
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>').replace({ upload: '<FILE_PATH>' })
console.log(asset.uid, asset.filename)
} 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: replace the file with a Buffer and new details
import { readFile } from 'node:fs/promises'
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const bytes = await readFile('<FILE_PATH>')
const asset = await stack.asset('<ASSET_UID>').replace(
{
upload: bytes,
filename: 'hero-v2.png',
content_type: 'image/png',
title: 'Homepage hero image',
description: 'Updated hero image for the spring campaign',
tags: 'campaign,homepage',
parent_uid: '<FOLDER_UID>'
},
{ relative_urls: true }
)
console.log(asset.filename, asset.url)
} catch (error) { console.error(error.errorMessage) }unpublish
unpublish unpublishes an asset from the environments and locales you name, now or at a scheduled time.
| Name | Type | Description |
|---|---|---|
| options (required) | PublishConfig | Targets and request options. |
| options.publishDetails (required) | PublishDetails | Target environments and locales. |
| options.publishDetails.environments (required) | string[] | Environment names to unpublish from. |
| options.publishDetails.locales (required) | string[] | Locale codes to unpublish from. |
| options.locale | string | Locale sent as the top-level locale key. |
| options.version | number | Asset version to unpublish. |
| options.scheduledAt | string | ISO 8601 date and time to unpublish later. |
| options.headers | Record<string, string> | Extra headers for this request only. |
| options.params | Record<string, unknown> | Query parameters for this request. |
Returns: Promise<Response>. The API response with the unpublish notice.
Warning unpublish removes the asset from the environments you name, so delivery requests on those environments stop returning it. Publish the asset again to restore it.
Validation
- There is no client-side validation of the targets. The SDK sends publishDetails as you pass it.
- Calling unpublish() with no argument returns a promise that rejects with TypeError, because unpublish reads its options from one object.
- unpublish exists only on stack.asset('<ASSET_UID>'). On stack.asset() 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
- One call sends one Unpublish an asset request (POST /v3/assets/{asset_uid}/unpublish).
- The SDK builds the JSON body as { "asset": publishDetails } and adds locale, version and scheduled_at when you set them. It renames scheduledAt to scheduled_at.
- options.headers merge over the headers of this object for this request only. options.params go in the query string.
- Without scheduledAt, the API unpublishes the asset now. With it, the API schedules the unpublish for that time.
- unpublish resolves to the response body, which holds notice.
Example
Basic usage: unpublish an asset from one environment now
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.asset('<ASSET_UID>').unpublish({
publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'] }
})
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: schedule an unpublish of version 2 on another branch
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.asset('<ASSET_UID>').unpublish({
publishDetails: { environments: ['<ENVIRONMENT>'], locales: ['<LOCALE>'] },
locale: '<LOCALE>',
version: 2,
scheduledAt: '2026-12-01T09:00:00.000Z',
headers: { branch: '<BRANCH>' },
params: { include_branch: true }
})
console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }update
update saves the title, description and other properties that you set on an asset object.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
| param.include_branch | boolean | Adds the _branch key to the asset. |
Returns: Promise<Asset>. The updated asset.
Validation
- There is no client-side validation. update sends whatever properties the object holds.
- update exists only on stack.asset('<ASSET_UID>'). On stack.asset() 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
- One call sends one Update asset request (PUT /v3/assets/{asset_uid}) with a JSON body and param as query parameters.
- update takes no body argument. The SDK builds the body as { "asset": { ... } } from the properties of the object. It leaves out uid, urlPath, stackHeaders, api_key and the created, updated and deleted metadata.
- Set the properties first, in one of two ways:
- On an asset from fetch, change the properties you want. The body then also carries the other fetched fields, such as url and filename.
- On stack.asset('<ASSET_UID>') with no fetch, set only title and description. The body then holds only those properties.
- The API updates the metadata of the asset. To change the file, use the replace method.
- update resolves to a new Asset that the SDK builds from the response.
Example
Basic usage: change the title and description of a fetched asset
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()
asset.title = 'Homepage hero image'
asset.description = 'Hero image for the spring campaign'
const updated = await asset.update()
console.log(updated.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: send only the new title, with the branch key in the response
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
// No fetch, so the request body holds only the title
const asset = stack.asset('<ASSET_UID>')
asset.title = 'Homepage hero image'
const updated = await asset.update({ include_branch: true })
console.log(updated.title, updated._branch)
} catch (error) { console.error(error.errorMessage) }