Editions

An Edition is an isolated container of your entire site within a space — for example live, staging, or a seasonal fall edition. Everything inside an edition is independent: content, markets, locales, webhooks, and preview URLs. Anything you change in one edition stays in that edition and never leaks into another.

Note

Editions were previously called Environments. The concept is the same — an isolated stage of your site — but the name across the UI, API, and database is now Edition.

The model

Org → Space → Edition → Market → content (pages, per Locale)
                 │         └── Default market; others inherit and override it
                 └── isolated container; cloning forks it; the live pointer flips per edition

• Markets live inside an edition. Each edition has its own set of markets and its own default market. The germany market in your fall edition is a different thing from germany in live.
• The live delivery key targets one edition. That’s the edition your production storefront serves.

Default edition

Every space starts with a single default edition (typically main). This is the edition your production storefront should point to.

Creating and cloning editions

Go to Settings → Editions and click New Edition. You can create as many as you need.

Cloning an edition deep-copies it — its pages, markets, and overrides — into a new, independent edition. From that point on the copy evolves on its own; nothing flows back to the original. Use a clone to stage a coherent set of planned changes (a seasonal redesign, decommissioning a market) without touching what’s currently live.

Why use multiple editions?

• Stage and review content changes in staging before they reach live.
• Prepare a seasonal edition (fall, spring-sale) ahead of time and flip the live pointer when it’s ready.
• Keep experimental work isolated from production content.

Edition context in API requests

Management API requests carry the edition via the X-Alokai-CMS-Edition header. If omitted, the request falls back to the space’s default edition.

curl -H "X-Alokai-CMS-Space: default" \
     -H "X-Alokai-CMS-Edition: staging" \
     -H "Authorization: Bearer <key>" \
     https://your-worker.workers.dev/api/pages

Delivery API

The delivery API (used by the storefront) accepts ?edition=<id> as a query parameter:

GET /api/v1/pages/by-path/about?edition=staging&locale=en-US

See Markets & Overrides for how content resolves within an edition, and Publishing for how a page goes live.