Studio Provisioning API Reference
Provisioning a Studio project by API means two services in the same breath: the CMA creates the stack, environments and tokens, and the Studio API creates the project that points at them. This page covers the part that isn’t obvious from either service’s own reference: which pair of hosts to call, and in what order.
The route shapes themselves live elsewhere. Projects: the five project routes documents every /v1/projects request and response, and Authentication and authorization documents the credential headers. This page assumes both.
Do It With a Skill
provision-studio-project performs this call order for you, and authenticate-cma is the credential ladder every call here assumes.
curl -fsSL https://studio-documentation.contentstackapps.com/install.sh | sh
The Two Hosts Every Provisioning Run Needs
A provisioning run talks to two hosts, and they must be the same region. The Studio API host is derived from the CMA host you’re already using:
| CMA host | Paired Studio API host |
|---|---|
| api.contentstack.io (AWS NA, the default) | composable-studio-api.contentstack.com |
| eu-api.contentstack.com | eu-composable-studio-api.contentstack.com |
| azure-na-api.contentstack.com | azure-na-composable-studio-api.contentstack.com |
| azure-eu-api.contentstack.com | azure-eu-composable-studio-api.contentstack.com |
For any host not named above, the derivation is mechanical: replace the -api. segment with -composable-studio-api.. That rule covers the regions this table doesn’t name.
Editor hosts are not CMA hosts. app.contentstack.com and its regional variants serve the Contentstack UI and the Live Preview clientUrlParams.host; CMA requests sent there fail. The same substitution derives a Studio API host from an editor host, replacing -app. with -composable-studio-api., but the editor host itself never receives a provisioning call.
Two authoritative lists sit behind this one. The full set of Studio API base URLs, including the GCP and AWS AU regions, is in Base URL & versioning. For CMA hosts, use Contentstack’s Content Management API endpoints, which lists every AWS, Azure and GCP region and stays current as regions are added.
Why the pairing is the thing that bites
A mismatched pair does not error. Point the CMA at one region and the Studio API at another and both services answer normally: the stack, tokens and project all get created, each in whichever data center its own host names. The calls return 200 and 201. Nothing in either response says the two halves ended up apart.
The common shape of this mistake is omitting the host override entirely while working against a non-prod environment. Both SDKs then fall back to their AWS NA prod defaults, and a run intended for a non-prod environment provisions a content type, a delivery token and a Studio project into production instead. Establish the data center before the first call, not after.
Non-Prod Environments
QA, staging and internal dev environments sit on their own domain, and no region shortcut reaches them. Every host has to be set explicitly.
Ask for the two values rather than deriving them. The hosts follow the pattern <env>-<service>.<non-prod-domain>, but both halves are specific to your organization: read <env> and <non-prod-domain> off the URL you already open Contentstack at, or ask whoever runs the environment. Guessing either one produces hosts that resolve to nothing, or worse, to the wrong data center.
| Service | Non-prod host | Role in provisioning |
|---|---|---|
| CMA | <env>-api.<non-prod-domain> | Stack, environments, tokens, content types |
| Studio API | <env>-composable-studio-api.<non-prod-domain> | Project creation and configuration |
| Editor (browser) | <env>-app.<non-prod-domain> | The Studio UI a person opens afterwards |
The regional host map in install-studio carries the matching CDA, Live Preview and image hosts for the same environments, which the consuming app needs at runtime.
Call Order
Each step depends on the one above it, so a run that fails partway leaves a coherent prefix rather than a broken stack.
- Validate the credential. GET /v3/user?include_orgs=true against the CMA host confirms the token resolves and returns the organizations it can reach.
- Choose the organization. Project creation is scoped to one, and a token with access to several gives no default.
- Find or create the stack. A new stack takes a master locale, en-us unless the project needs otherwise.
- Ensure the environments. Studio resolves a composition’s canvas against an environment’s base URL, so the environments exist before the project points at them.
- Enable Live Preview on the stack, via read-modify-write on POST /v3/stacks/settings with live_preview.enabled, the environment uid in default-env and a default-url. Not PUT /v3/stacks: that answers 200 and silently discards the payload. Contentstack’s own UI makes the same call: saving a stack’s Visual Experience settings issues POST /v3/stacks/settings and returns 201 Created. enabled: true alone is rejected 422, which is why the environment comes first.
- Generate the delivery token and the preview token. Either in one call or two. POST /v3/stacks/delivery_tokens?create_with_preview_token=true returns both, measured: 201, with a 26-char cs… value at token.preview_token. The flag works only as a query param; placed in the body it is accepted and the token is silently absent. The alternative is POST /v3/stacks/delivery_tokens followed by POST /v3/stacks/delivery_tokens/{uid}/preview_token, which is what scripts/provision.ts does because it is unconditional. Whichever route you take, assert the preview token is non-empty before writing it: an empty one 401s every Preview API call without saying so.
- Create the Studio project. POST /v1/projects on the paired Studio API host. See Create a project for the body.
- Configure the project. PUT /v1/projects/{uid}/configuration sets the environment, locale and canvas URL.
Steps 1 through 6 are CMA calls; 7 and 8 are Studio API calls. That boundary is where a mismatched host pair goes unnoticed.
The Canvas URL is a Path, Not a URL
canvas_url in the configuration call takes a relative path, such as /canvas. The origin belongs to the environment’s base URL, and Studio joins the two at render time.
Passing a full URL (http://localhost:3006/canvas) is accepted and then hard-codes the project to a single environment, so per-environment preview stops working. Reject the full-URL form at the call site rather than letting it reach the API. Canvas URL covers how the two halves combine.
Pitfalls
| Pitfall | Why it bites | Fix |
|---|---|---|
| CMA host and Studio API host from different regions | Every call succeeds. The stack lands in one data center, the project in another, and nothing reports it | Derive the Studio API host from the CMA host with the table above; never set them independently |
| No host override on a non-prod run | Both services fall back to AWS NA prod defaults, so a dev run provisions into production | Set both hosts explicitly. Non-prod has no region shortcut |
| Wrong region CMA host | 401 or 404 on every call, before anything is created | Use the region host from Contentstack’s API endpoints list |
| Expecting the preview token from a plain POST /v3/stacks/delivery_tokens | Without ?create_with_preview_token=true there is no token.preview_token on the response. Reading it anyway yields undefined, which gets written into the environment and 401s every Preview API call | Either pass the flag as a query param, or call POST /v3/stacks/delivery_tokens/{uid}/preview_token. Assert the value is non-empty before writing it |
| canvas_url set to a full URL | Accepted, then pins the project to one environment and breaks per-environment preview | Pass a relative path such as /canvas |
| Project created before its environment exists | Configuration references an environment the stack doesn’t have | Keep the order: environments at step 4, project at step 7 |
| Caller-supplied management token | The Studio API relays a session or OAuth credential only, and never a non-Bearer authorization value | Use a session authtoken or an OAuth Bearer token. See Authentication and authorization |
See Also
- Projects: the five project routes: every /v1/projects request and response shape.
- Studio API: the managed Studio service: base URLs by region, and the credential contract.
- Studio API: errors and validation: what each failure code means.
- Canvas URL: how the environment base URL and the canvas path combine.
- Create a Studio project: the same outcome through the Studio UI.