Environments
Promote one approved version through pre-production stages, such as dev and staging, before it reaches prod. Nothing is rebuilt between stages: the exact snapshot that passed review moves forward.
The environments themselves are platform-wide. An admin defines them once, in promotion order, and each one is served by a gateway (below). Every API promotes along that same path; an API only chooses which of the pre-production environments it uses.
Environments are optional per API. An API without stages works as before: publishing makes it live in prod.
How it works
| Without stages | With stages | |
|---|---|---|
| Approve & Publish | The working copy goes live in prod | The approved version is deployed to the first stage |
| Prod | The working copy, while published | The version promoted to prod, served from its snapshot |
| Pull Back to Draft | Takes the API offline | Prod keeps serving its version while you draft, review and test the next one |
| Restore live (version history) | Puts the snapshot back live | Deploys the snapshot straight to prod |
Each environment serves:
- Spec: from the deployed snapshot.
- Base URL: each stage can have its own upstream base URL; leave it blank to use the deployed version's main base URL. Prod always uses the snapshot's base URL.
- Credential: a stage can have its own upstream credential, otherwise it uses the API's main one; prod always uses the main one.
- Mappers: from the deployed snapshot, so a mapper change moves through the environments with its version.
- Shared by all environments: gateway policy, TLS settings and masking.
Set up stages
In the API's Environments card, click Configure. Every platform environment is listed in promotion order with a switch. Switch on the stages this API goes through, optionally give each a base URL and a credential, and click Save environments. Switching one stage on never changes another: to go from dev to dev + uat, leave Dev on and switch UAT on. Prod is always on and comes last. If only prod is listed, an admin needs to add environments first.
A stage's base URL is the service the stage calls (for example a dev backend such as https://dev-api.example.com). It is never the stage's gateway URL: Studio serves each stage itself at …/gw/<catalog>/<api>/<stage>. Studio refuses its own address there. If dev and prod call the same service, leave the base URL blank.
When an admin has set Allowed upstream hosts (API Builder › Gateway settings), a stage base URL must use one of those hosts, like the main base URL.
If the API is already live when you add stages, prod is pinned to the version agents use today, so nothing changes for them. Switching off a stage that serves a version asks for confirmation first, because its gateway URL stops working. Switching every stage off turns environments off.
Who can set up stages:
- An
api_developer, while the API is being built: a draft (or sent back) with nothing deployed in any environment. - A
lifecycle_manager,space_adminoradmin, at any time. Once a version is deployed or in review, only they can change the stages.
Promote
Each environment card shows the version it serves and when it was deployed. Promote to … moves that version to the next environment; promoting to prod updates the tool that Studio agents call immediately. Every deploy is in the audit log (DEPLOY_ENVIRONMENT).
Calling a stage
Prod stays at …/gw/<catalog-slug>/<api-slug>/…. Each stage has its own URL, with the stage's name after the API's slug:
/gw/<catalog-slug>/<api-slug>/<stage>/<operation path>
The gateway treats the first path segment as a stage only when it names one of this API's stages; anything else is a prod path. So if a stage's name is also the first segment of one of the API's paths (a stage v1 and an operation /v1/orders, or /{id} called with the id staging), prod calls to that path go to the stage. Pick stage names that never start a path, or call such operations through the permanent ID URL.
The Endpoints card on the API page lists every complete URL per environment. The permanent ID URLs (/api/v1/api-definitions/<id>/proxy/… and /api/v1/api-definitions/<id>/env/<stage>/proxy/…) keep working too.
Use the gateway secret, or a consumer key created for that environment: a key only works in the environment it was made for. The test console can target any environment, or the saved working copy.
Each environment has its own circuit breaker and cache, so a failing staging upstream never affects prod.
Platform environments and gateways
Admin → Dashboard → API Platform (admins only) holds two lists:
- Environments: the pre-production environments in promotion order, plus
prod, which is always last and is what Studio agents use. Each has a fixed id (used in URLs, stage names and consumer keys, so it can't be renamed), a display name, a status and the gateway serving it. Up to 5 pre-production environments. - Gateways: the runtime serving an environment. The Built-in gateway (Studio's own proxy) serves everything by default. Adding another gateway lets you give environments their own default policy (rate limits, GET cache and so on, applied under each API's own gateway policy) and suspend them independently. Today every gateway runs inside Studio; the model leaves room for external gateways later.
Effects:
| Action | Result |
|---|---|
| Suspend an environment | Every API returns 503 in that environment; other environments keep working |
| Suspend a gateway | Every environment it serves returns 503 |
| Gateway default policy | Fills in any setting an API doesn't set itself (API setting → gateway default → server default) |
| Reorder environments | Every API's stages are put in the new order at once; what each stage serves is unchanged |
| Delete an environment | Refused while any API uses it as a stage or an unrevoked consumer key is bound to it; suspend it instead |
| Gateway public base URL | API pages show each environment's URL under the base URL of the gateway serving it (e.g. a reverse proxy's host) |
Changes reach other server replicas within about 10 seconds.
On upgrade, every stage name already used by an API becomes a platform environment on the built-in gateway, so existing APIs keep working unchanged.
API
PUT /api/v1/api-definitions/{id}/environments {"stages": [{"name": "dev", "upstream_base_url": "https://dev.example.com", "auth_key": "…"}]}
POST /api/v1/api-definitions/{id}/promote {"environment": "dev"}
GET /api/v1/api-definitions/{id}/gateway-health → per environment: version served and breaker state
Platform settings are under /api/v1/api-platform (reads for API Builder users, changes for admins):
GET /api/v1/api-platform/environments → in promotion order, prod last
POST /api/v1/api-platform/environments {"slug": "staging", "name": "Staging", "gateway_id": "built-in"}
PATCH /api/v1/api-platform/environments/{slug} {"name": …, "gateway_id": …, "status": "active" | "suspended"}
PUT /api/v1/api-platform/environments/order {"slugs": ["dev", "staging"]}
DELETE /api/v1/api-platform/environments/{slug}
GET /api/v1/api-platform/gateways
POST /api/v1/api-platform/gateways {"name": "Staging gateway", "base_url": null, "default_policy": {"rate_limit_per_minute": 100}}
PATCH /api/v1/api-platform/gateways/{id} {"name": …, "base_url": …, "default_policy": …, "status": …}
DELETE /api/v1/api-platform/gateways/{id} (not the built-in one, nor one still serving an environment)
environments on the API definition shows each stage's base URL and deployment; stage credentials are always returned as •••••••• (send that back unchanged to keep one).