Concepts
The mental model — registry, specs, mocks, governance, versioning.
The shape of Spec0
Four primitives. Everything else is composition.
| Primitive | What it is | Where it lives |
|---|---|---|
| Spec | An OpenAPI document — a versioned, immutable snapshot. | The registry. |
| API | A logical service identified by <org>/<name>. Owns a stream of specs. | The registry, scoped to a team. |
| Mock | A live HTTP server bound to a published spec. | mocks.spec0.io/m/<id>. |
| Grant | A consumer team's approved permission on another team's API. | The registry. |
Specs are immutable
Every spec0 publish produces a new spec. Old versions don't disappear; consumers can pin to any tag. Spec0's diff compares any two and answers is this a breaking change deterministically — it's the gate --semver uses to decide between patch, minor, and major bumps.
The registry is the source of truth
If a service can talk to the registry, it can:
- discover what APIs exist
- pull the latest spec for any of them
- subscribe and get notified on changes
- publish updates (with permission)
The CLI, the dashboard, and CI runners are all clients of the same REST surface. So are AI agents over MCP: an authenticated agent reaches the registry through the org-scoped Spec0 MCP server (search_apis, get_api_spec, list_apis) — token-scoped to your org, just like every other client. The agent searches your specs, pulls a full document, and lists your APIs without you hand-feeding it anything.
Mocks track specs, not the other way around
A mock is provisioned from a published spec. Update the spec and the mock follows on the next refresh. There is no parallel "mock definition" to keep in sync — the mock is the spec interpreted by the mock server engine.
Governance is opt-in
You can publish without lint rules, without breaking-change gates, without team ownership. Quality controls are layers you add — --min-score, --save-ruleset, team policies — when a contract becomes load-bearing.
Versioning, briefly
pull <api>@<tag>— fetch a specific version.pull <api>@latest— fetch the head of the stream.diff <a> <b>— works against files or registry refs.log <api>— chronological tag list.
The canonical CI gate lives in block-on-breaking-changes.
Setup walkthrough
A guided, end-to-end tour of Spec0 — set up a team, publish your first API, connect an AI agent, add governance, and open it to the world. Every step explained, with recommendations along the way.
Platform
API management for engineering orgs — versioned internal APIs, owned by teams, consumed with explicit permissions, accessible from AI agents and CI.