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 current 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. Publish to an environment 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. Your pipeline decides which environment moves, and when.

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

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.

An environment can also exist without a URL. That's fine: it still scopes the spec version and any per-environment parameters you set on the API's Environments tab.

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 current in 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.