Environments

An environment is a named context an API serves in — staging, production, canary, whatever your org uses. Each environment of an API carries two things: the URL the API serves at there, and the spec version that is current in that environment.

The important part: those versions are independent. Staging can be three releases ahead of production. Spec0 tracks "which version is live where" per environment, so the spec a consumer sees always matches the environment they're targeting.

Per-environment spec versions

When you publish a spec, Spec0 stores it as a version. An environment then points at one of those versions — the one that is current there. Promote or publish, and only that environment's pointer moves; the others stay put.

In the dashboard, open an API and use the environment selector on the Reference → Spec tab to view the exact spec each environment is serving. An API with no environments just shows its latest spec, as before.

Publishing to an environment

Point a publish at an environment with --env:

spec0 push openapi.yaml --env staging
spec0 push openapi.yaml --env production

That advances the named environment to the version being published, and leaves every other environment untouched. This is the natural fit for CI:

# on the main branch → staging
- run: spec0 push openapi.yaml --env staging

# on the release branch → production
- run: spec0 push openapi.yaml --env production

Publish from main to keep staging current, and from your release branch to move production. In a git-driven setup, this is promotion — there's no separate step. The branch that ran the publish decided which environment moved.

Omitting --env publishes a new version without touching any environment pointer — the unchanged default.

Promotion

Promotion is moving an environment to the version that is already current in another environment — for example, "make production serve what staging is serving." There are two ways it happens, and an org picks which.

Git-driven (recommended for CI)

The environment pointers are moved only by your pipeline, using spec0 push --env as shown above. Your branches are the source of truth for what's live where. When an API is git-driven, the dashboard's manual Promote action is turned off, so the two paths can't disagree.

Manual (the console)

For teams not wiring this into CI, open the API's Environments tab in the dashboard and use Promote on the source environment. You pick the target, see a diff preview of what would change (including whether it introduces breaking changes), and confirm. The target environment then serves the source's current version.

Choosing the mode

The mode is an org-wide default with a per-API override:

• Set the org default under Settings → Profile & branding → Promotion (Manual or Git).
• Override it on an individual API from the API's settings.

An API uses its own override when set, otherwise the org default, otherwise Manual.

Governance gates on promotion

An environment can require your governance policy to pass before a promotion into it is allowed — the lever for "strict production, relaxed staging."

Turn on Enforce governance on promote for an environment (per-API, in the Environments tab). When it's on, promoting a spec into that environment runs your org's governance policy against it; any blocking violation rejects the promotion and the environment stays on its current version. Leave it off — the default — and promotions into that environment aren't gated.

A typical setup: enforce on production, leave staging open, so teams iterate freely in staging and only clean specs reach production.

Environment URLs

Each environment has the URL its API serves at. Spec0 reads it from the servers block of the spec you publish, so a spec like this populates the right URL per environment automatically:

servers:
  - url: https://staging.api.example.com
    x-spec0-environment: staging
  - url: https://api.example.com
    x-spec0-environment: production

A templated server works too:

servers:
  - url: https://{environment}.api.example.com
    variables:
      environment:
        default: production
        enum: [staging, production]

If you set an environment's URL by hand in the dashboard, that wins — a later publish won't overwrite it.

Reading an environment's spec from an agent

The org-scoped MCP tool get_api_spec takes an optional environment name, so an AI agent — or anything on the MCP surface — can fetch the spec current in a given environment instead of the latest:

• get_api_spec(apiId, "production") → the version promoted to production.
• get_api_spec(apiId, "staging") → the version in staging.
• Omit it (or pass an environment with no pinned version) → the API's latest spec.

This stays an internal, org-scoped surface: the public registry and generated SDKs remain environment-less.