Asset

View as Markdown

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

CapabilitySupportedNotes / Alternative
Upload from a readable streamNoupload accepts a file path or a Buffer. Read the stream into a Buffer first
Name asset versions or list asset versionsNoThe SDK has no asset version methods. Send the Asset Versions requests of the CMA with your own HTTP client
Publish many assets in one requestNoUse the publish method of BulkOperation
Receive a Blob from download in Node.jsNoIn 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 NameReturnsDescription
createThe new asset.Uploads a file as a new asset.
queryA query for assets, sent when you call find(), findOne() or count().Builds a query for the assets of the stack.
folderA 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 NameReturnsDescription
fetchThe requested asset.Retrieves one asset.
updateThe updated asset.Saves the title, description and other changed properties.
replaceThe asset with its new file.Replaces the file of an asset.
getReferencesThe entries and content types that reference the asset.Lists where the asset is in use.
publishThe API response with the publish notice.Publishes the asset.
unpublishThe API response with the unpublish notice.Unpublishes the asset.
deleteThe API response with a notice.Deletes the asset.

Download a file. The method in the table below is available on both forms.

Method NameReturnsDescription
downloadThe 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 NameReturnsDescription
addHeaderThe same asset, for chaining.Adds one request header.
addHeaderDictThe same asset, for chaining.Adds several request headers.
removeHeaderThe 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.

NameTypeDescription
key (required)string

Name of the request header.

Default: Not applicable
value (required)string

Value of the request header.

Default: Not applicable

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.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

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.

NameTypeDescription
data (required)AssetData

Form fields and the file to upload.

Default: Not applicable
data.upload (required)string | Buffer

Path of the file, or its bytes.

Default: Not applicable
data.filenamestring

File name sent with a Buffer upload.

Default: 'uploaded_file'
data.content_typestring

MIME type of the file.

Default: From the file extension, or 'application/octet-stream'
data.titlestring

Title of the asset.

Default: undefined (not sent)
data.descriptionstring

Description of the asset.

Default: undefined (not sent)
data.tagsstring[] | string

Tags. The SDK joins an array with commas.

Default: undefined (not sent)
data.parent_uidstring

UID of the folder for the asset.

Default: undefined (not sent)
paramsAnyProperty

Query parameters for the request.

Default: undefined (sends no query parameters)
params.relative_urlsboolean

Returns a relative URL in url.

Default: API default
params.include_dimensionboolean

Adds the image height and width.

Default: API default

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}

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.

NameTypeDescription
options (required)object

URL, response type and extra headers.

Default: Not applicable
options.urlstring

File URL. Required on stack.asset().

Default: The url property of the asset
options.responseTypeAssetResponseType

Format of data, such as arraybuffer or stream.

Default: undefined (the response body as a string)
options.paramsobject

Extra request headers, not query parameters.

Default: undefined (adds no headers)

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}
param.versionnumber

Asset version to retrieve.

Default: API default (latest version)
param.include_pathboolean

Adds the path of the parent folders.

Default: API default
param.environmentstring

Returns the asset as published on this environment.

Default: API default
param.include_publish_detailsboolean

Adds the publish details of the asset.

Default: API default
param.relative_urlsboolean

Returns a relative URL in url.

Default: API default
param.include_metadataboolean

Adds the asset metadata under _metadata.

Default: API default
param.include_branchboolean

Adds the _branch key to the asset.

Default: API default

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.

NameTypeDescription
folderUidstring

UID of the folder. Omit it to create folders.

Default: null (returns the collection form)

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}
param.include_publish_detailsboolean

Adds the publish details of the asset.

Default: API default
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

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.

NameTypeDescription
options (required)PublishConfig

Targets and request options.

Default: Not applicable
options.publishDetails (required)PublishDetails

Target environments and locales.

Default: Not applicable
options.publishDetails.environments (required)string[]

Environment names to publish on.

Default: Not applicable
options.publishDetails.locales (required)string[]

Locale codes to publish on.

Default: Not applicable
options.localestring

Locale sent as the top-level locale key.

Default: null (not sent)
options.versionnumber

Asset version to publish.

Default: null (not sent)
options.scheduledAtstring

ISO 8601 date and time to publish later.

Default: null (runs now)
options.headersRecord<string, string>

Extra headers for this request only.

Default: {}
options.paramsRecord<string, unknown>

Query parameters for this request.

Default: {}

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().

NameTypeDescription
paramsobject

Query parameters for the request.

Default: {}
params.queryobject

Filter, sent as query=<JSON>.

Default: undefined (no filter)
params.folderstring

Folder UID, or cs_root for the root folder.

Default: API default
params.include_foldersboolean

Adds folders to the results.

Default: API default
params.include_countboolean

Adds the total number as count.

Default: API default
params.environmentstring

Returns assets published on this environment.

Default: API default
params.include_publish_detailsboolean

Adds the publish details of each asset.

Default: API default
params.relative_urlsboolean

Returns relative URLs in url.

Default: API default
params.ascstring

Field UID to sort by, ascending.

Default: API default
params.descstring

Field UID to sort by, descending.

Default: API default
params.include_branchboolean

Adds the _branch key to each asset.

Default: API default

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.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

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.

NameTypeDescription
data (required)AssetData

Form fields and the new file.

Default: Not applicable
data.upload (required)string | Buffer

Path of the new file, or its bytes.

Default: Not applicable
data.filenamestring

File name sent with a Buffer upload.

Default: 'uploaded_file'
data.content_typestring

MIME type of the file.

Default: From the file extension, or 'application/octet-stream'
data.titlestring

New title of the asset.

Default: undefined (not sent)
data.descriptionstring

New description of the asset.

Default: undefined (not sent)
data.tagsstring[] | string

Tags. The SDK joins an array with commas.

Default: undefined (not sent)
data.parent_uidstring

UID of the folder for the asset.

Default: undefined (not sent)
paramsAnyProperty

Query parameters for the request.

Default: undefined (sends no query parameters)
params.relative_urlsboolean

Returns a relative URL in url.

Default: API default

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.

NameTypeDescription
options (required)PublishConfig

Targets and request options.

Default: Not applicable
options.publishDetails (required)PublishDetails

Target environments and locales.

Default: Not applicable
options.publishDetails.environments (required)string[]

Environment names to unpublish from.

Default: Not applicable
options.publishDetails.locales (required)string[]

Locale codes to unpublish from.

Default: Not applicable
options.localestring

Locale sent as the top-level locale key.

Default: null (not sent)
options.versionnumber

Asset version to unpublish.

Default: null (not sent)
options.scheduledAtstring

ISO 8601 date and time to unpublish later.

Default: null (runs now)
options.headersRecord<string, string>

Extra headers for this request only.

Default: {}
options.paramsRecord<string, unknown>

Query parameters for this request.

Default: {}

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {}
param.include_branchboolean

Adds the _branch key to the asset.

Default: API default

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