Skip to main content
Contentstack MCP profile hub is in general availability!

Releases, bulk publish and nested reference publishing, explained

•
7 min read

Contentstack has three ways to get a lot of content live at once, and they solve different problems. A release controls when a reviewed set of versions goes live, bulk publish pushes a large number of entries out right now, and nested reference publishing makes sure a page goes live together with the content it points to. Pick the wrong one and you get a launch page with a missing hero, or a script that hits rate limits halfway through.

The short version

If you only read one section, read this one.

  • Use a release when a fixed set of entry and asset versions has to go live together, usually at a scheduled moment.

  • Use bulk publish when you need to push many entries to environments now, from a script, the CLI, or the UI.

  • Use nested reference publishing when you publish a page and want everything it references to go with it, up to five levels deep.

The rest of this post is the detail behind those three lines, with the calls to make each one happen.

Releases are about timing

A release is a named bundle of entries and assets. Each item in a release carries an entry or asset UID, a locale, a version, and an action (publish or unpublish). You deploy the release to one or more environments, immediately or at a scheduled time.

The version is the important part. When you add an entry to a release, you add a specific version of it. If an editor saves a newer version afterwards, the release still deploys the version you added until someone updates the item. That is exactly what you want for a launch: the content that was reviewed is the content that ships.

Releases are branch-specific. A release on main deploys items from main, and you cannot mix branches in one release.

Here is the full flow with the JavaScript Management SDK: create a release, add items, deploy it.

import * as contentstack from '@contentstack/management';

const stack = contentstack
  .client()
  .stack({
    api_key: process.env.CS_API_KEY,
    management_token: process.env.CS_MANAGEMENT_TOKEN,
  });

const release = await stack.release().create({
  release: { name: 'Spring launch', description: 'Product page and hero' },
});

await stack.release(release.uid).item().create({
  items: [
    { uid: 'blt_product', version: 4, locale: 'en-us', content_type_uid: 'product', action: 'publish' },
    { uid: 'blt_hero', version: 2, locale: 'en-us', content_type_uid: 'hero', action: 'publish' },
  ],
});

await stack.release(release.uid).deploy({
  environments: ['production'],
  locales: ['en-us'],
  action: 'publish',
  scheduledAt: '2026-12-01T09:00:00.000Z',
});

Leave out scheduledAt to deploy right away. When you add items in bulk, the API accepts at most 25 items per request, so chunk the array for bigger launches.

Bulk publish is about volume

Bulk publish takes a list of entries and assets and publishes them to environments and locales in one request. There is no bundle to manage and no version pinning beyond what you put in the request. It is the right tool for "publish everything in this content type to staging" or "republish these 400 entries after a model change."

The endpoint is POST /v3/bulk/publish:

curl -X POST "https://api.contentstack.io/v3/bulk/publish" \
  -H "api_key: $CS_API_KEY" \
  -H "authorization: $CS_MANAGEMENT_TOKEN" \
  -H "api_version: 3.2" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      { "uid": "blt_post_1", "content_type": "blog_post", "version": 3, "locale": "en-us" },
      { "uid": "blt_post_2", "content_type": "blog_post", "version": 7, "locale": "en-us" }
    ],
    "locales": ["en-us"],
    "environments": ["production"]
  }'

The response returns a job_id. Bulk publish is asynchronous, so a successful response means the job was accepted, not that the content is live. Check the job with GET /v3/bulk/jobs/{job_id} and its items with GET /v3/bulk/jobs/{job_id}/items, both with the api_version: 3.2 header.

Two query parameters matter if you use workflows. skip_workflow_stage_check=true publishes the entries that are at a stage that satisfies your publish rules. approvals=true publishes the entries that don't need an approval.

The limits are tight on purpose. The API reference lists 10 entries in 10 locales and 10 environments per request, and bulk actions are limited to one request per second instead of the usual ten. For anything bigger, you need a loop with batching and backoff, which is where the CLI comes in.

The CLI does the batching for you

In CLI 2.x, bulk publishing lives in the bulk operations plugin and ships with the CLI. The old cm:entries:publish command is gone. Its replacement is cm:stacks:bulk-entries:

csdx cm:stacks:bulk-entries \
  --operation publish \
  --content-types blog_post \
  --environments production \
  --locales en-us \
  --filter modified \
  --branch main \
  -a my-token-alias

A few flags do most of the work:

  • --filter picks entries by status: draft, modified, unpublished, or non-localized.

  • --publish-mode bulk (the default) uses the Bulk Publish API. single makes one call per entry.

  • --source-env with --source-alias cross-publishes whatever is live in one environment to another.

  • --include-variants adds entry variants to the run.

Every run writes success and failure logs to a bulk-operation folder. --retry-failed ./bulk-operation republishes only the failures, and --revert ./bulk-operation undoes a run from its success log. That revert alone is a good reason to use the CLI over a hand-rolled script. Assets have their own command, cm:stacks:bulk-assets, with similar publish flags.

Nested reference publishing is about dependencies

Publishing a page entry does not publish the entries it references. If your page references a new hero, which references a new CTA, publishing the page gives you a page that points at content the environment doesn't have yet. Nested reference publishing fixes that: you publish a parent and its referenced entries and assets go with it.

The rules are worth knowing before you rely on it:

  • References are followed up to five levels deep by default. The depth can vary by plan.

  • Publishing follows unpublished changes and stops at the last published version of a reference. If A references B and B references C, and only C changed since B was last published, publishing A does not include C. Publish B with its references, or C directly.

  • Entries and taxonomies already published to the target environment and locale are skipped.

  • If a nested entry fails, the entries below it are not sent.

  • Only two bulk publish jobs can be active across your organization at once.

  • It is a plan-based feature that your organization admin has to have enabled.

Through the API, nested reference publishing needs the api_version: 3.2 header. With the JavaScript Management SDK, pass is_nested: true and the version:

await stack.bulkOperation().publish({
  details: {
    entries: [{ _content_type_uid: 'page', uid: 'blt_landing_page' }],
    locales: ['en-us'],
    environments: ['production'],
  },
  is_nested: true,
  api_version: '3.2',
});

You list the parents. Contentstack walks their references.

Side by side

This is the table I'd pin above my desk:

Release

Bulk publish

Nested reference publishing

Solves

Many items live at one moment

Many items live now

A parent and its references live together

Picks versions

Yes, per item

Per request

Latest unpublished changes

Scheduling

Yes

No (use a release)

Yes, as a scheduled bulk job

Follows references

No

No

Yes, up to five levels

API

/v3/releases/{uid}/deploy

/v3/bulk/publish

/v3/bulk/publish with api_version: 3.2

CLI 2.x

None

cm:stacks:bulk-entries

None

Undo

Deploy an unpublish

--revert in the CLI

Unpublish the items

Where it goes wrong

The biggest trap is combining releases and nested references. Nested reference publishing is not supported when you publish through releases. If your launch release contains a landing page, it does not pull in the page's new hero. Add every referenced entry to the release yourself, and check the release before you schedule it.

The second trap is reading a 200 as "published." Both bulk publish and release deploys hand you a job. Your CI should poll the job status before it tells anyone the content is live, and before it triggers a frontend rebuild that expects the new content.

The third is workflows. If an entry fails a publish rule, a nested bulk publish does not proceed. That's correct behavior, but it surprises people who expected the rest of the tree to go through.

Concluding

Pick by the question you are answering. "When does this go live?" is a release. "How do I get all of this out?" is bulk publish, and in practice that means cm:stacks:bulk-entries. "Will this page work when it lands?" is nested reference publishing.

If you are wiring any of this into a pipeline, read Safe content model changes with branches and aliases for the model side, and Revalidate, prime or redeploy for what happens on the frontend after the content is live.

Frequently asked questions

  • Can I publish nested references through a release?

    No. Nested reference publishing is not supported when you publish entries through releases. Add the referenced entries to the release yourself.

  • How many items can one bulk publish API request handle?

    The API reference lists 10 entries in 10 locales and 10 environments per request, and bulk actions are limited to one request per second.

  • What does the api_version 3.2 header do?

    It is the API version that supports nested reference publishing. The bulk publish and job status endpoints list it as a required header.

  • Which CLI command replaces cm:entries:publish in CLI 2.x?

    cm:stacks:bulk-entries, from the bulk operations plugin that ships with CLI 2.x. It publishes or unpublishes entries in bulk with filters, retries and reverts.