Onboarding your organisation's APIs to spec0, step by step

This one is a guide rather than an argument. By the end of it your organisation’s APIs are in one registry, kept current from git, linted against a shared standard, mockable, queryable by your agents, and wired so the teams that depend on each API are recorded and hear about every change. Each step is a command or a screen, with a line on why it earns its place.

graph LR
    REPO["Your API repo"] -->|GitHub import or spec0 push| REG["spec0 registry"]
    REG --> GOV["Governance: lint + breaking-change gate"]
    REG --> MOCK["Hosted mock, always latest"]
    REG --> MCP["MCP: agents query one operation"]
    REG --> SUB["Subscriptions: consumers + change events"]

Before you start

The first person to sign up becomes the Org Owner. On first sign-in spec0 asks you to name your organisation before the dashboard opens, so you never land on a placeholder, and you can invite teammates in the same step. Every new org arrives with a sample Pet Store API in a Sample APIs team: it is a real, governed, MCP-queryable API you can poke at to see what the platform does, it does not count toward your real APIs, and you can delete it once you are oriented.

Then install the CLI and sign in:

npm install -g @spec0/cli
spec0 auth login

1. Get your specs in

There are two front doors, and they reach the same registry. Pick whichever fits how your specs already live.

Import from GitHub

If your spec is in a repository, the quickest way in needs no CLI at all. APIs → Import from GitHub is a four-step wizard: pick the repository, choose the spec file and its source branch, name the API and assign a team, then review the governance that will apply from the first publish. It needs the Spec0 GitHub App installed on the organisation that owns the repo; if your repository is not in the list, the picker links you to the install flow.

The source branch you choose becomes the API’s source of truth, and spec0 keeps reading it afterwards:

• Merges publish. A merge to that branch publishes a new version, tagged with the commit.
• Pull requests are checked. Breaking-change and lint results are posted as GitHub check runs and mirrored on the API’s Checks tab, so a breaking change shows up in the pull request before it merges.
• The API is read-only in the dashboard, marked Managed from GitHub. You publish by merging rather than clicking, so git stays the source of truth.

From the CLI

If you would rather drive it yourself, or the spec is not somewhere the App can reach, the CLI does the same job. From the repository that holds the document:

spec0 push ./openapi.yaml --name payments-api --team payments --semver

push publishes the spec privately, scoped to your org and the team you name, and captures where it came from automatically: inside a git repo it records the commit SHA, the GitHub repository, and the branch. --semver computes the next version by diffing against the last one, so a breaking change becomes a major bump without you deciding by hand. (spec0 publish is the sibling that puts a spec on the public registry with a shareable URL; for internal APIs, push is the one you want.)

To keep a CLI-published API current without hand-running it, generate a GitHub Actions workflow that runs the CLI for you:

spec0 ci generate github --spec-file openapi.yaml --branch main --write

Add two repository secrets, SPEC0_TOKEN and SPEC0_ORG_ID (a team-scoped service account token, not your personal one). From then on every pull request is linted and every merge republishes, skipping the publish when the spec has not changed.

2. Put your APIs under teams

Every API is owned by exactly one team, which is what keeps ownership from rotting to a departed individual. Create the teams your APIs belong to, in the dashboard under Teams → New team, or from the CLI:

spec0 team create payments

Name the team on publish with --team (a spec pushed without one lands in Unassigned APIs, which is a fine place to start and a bad place to stay). Invite people under Settings → Members → Invite, and give at least one person on each team the Team Admin role so the team can manage itself.

3. Turn on governance

Governance in spec0 starts with a shared Spectral ruleset, set for the whole organisation under Settings → API governance. The built-in rulesets (spectral:oas and friends) are available to everyone; a custom org ruleset that encodes your own standards needs a Pro plan. Once it is set, lint against it from the CLI or CI:

spec0 lint ./openapi.yaml --org-ruleset --min-score 80

Every API version gets a quality score, the share of rules it passes, visible on the dashboard and readable by agents through the get_api_health MCP tool. --min-score and --strict turn that score into a build gate, so a spec that falls below your bar fails CI rather than shipping quietly. Publishing can also reject a version outright when it introduces a breaking change or drops below a required score, so the contract has to clear the bar before it lands.

4. Register who consumes each API

This is the part most tooling skips: recording who depends on what. In spec0 that record is a subscription. A consumer team opens Subscriptions → New, picks the API, selects the specific operations it needs to call, and submits. The producing team sees the request under Subscribers and approves, trims, or rejects it.

The result is that the dependency between two teams stops being folklore and becomes a first-class fact: the producer can see exactly who is on each operation, and that list is what makes the next step possible.

5. Subscribe to changes, which is the same step

There is no separate “subscribe to updates” toggle to hunt for, because an active subscription already is one. Once a subscription is approved, that team is on the receiving end of the API’s events: a change log entry when a new version publishes, a breaking change alert when the new version is breaking, and any announcement the owner broadcasts. They land in each member’s inbox and the fuller notifications feed, with a daily email digest for anything left unread.

Tune where they go under Settings → Notifications for yourself, and Settings → Integrations for the org’s shared email and Slack channels. The point is that a breaking change reaches exactly the teams standing downstream of it, before it reaches their build.

6. Spin up a mock

A consumer waiting on an API does not have to wait. Generate a mock from the published spec:

spec0 mock create --api payments-api
spec0 mock url payments-api

That gives you a hosted mock at mocks.spec0.io/m/<id> that serves the latest published version of the contract and moves with it. Because it is generated from the spec rather than hand-written, it cannot drift the way a maintained-by-hand mock does, and it is free. Consumers build against the current contract while the real service is still being written.

7. Make it queryable by your agents

The last step is the one that makes the registry pay for itself in an agent-driven workflow. Wire the MCP server into your editor:

spec0 mcp install --client all

That points Cursor, Claude Code, and the like at https://api.spec0.io/mcp. Without a token an agent gets the documentation tools; with your token it gets org-scoped tools over your own indexed specs, so it can search your APIs, pull the single operation it needs, and read an API’s health, changelog, and owner. The agent queries the operation it needs instead of having a whole spec pasted into its context, which is the difference between roughly three hundred tokens and a hundred and fifty thousand.

Optional: bring your own AI key

If AI features are enabled for your org, add a provider key under Settings → Organization → AI provider to turn on Ask Spec0 chat, AI-written changelog summaries, and spec review. The key is encrypted, only the calling agent ever runs against your provider, and none of the MCP retrieval above depends on it.

What you have now

A handful of steps in, whether you came through the import wizard or the CLI, your organisation has a registry that stays current from git, a shared governance bar that fails the build when a spec falls short, an explicit record of which team consumes which operation, change events that reach exactly those teams, a mock per API that never drifts, and specs your agents can query one operation at a time. The platform docs go deeper on each surface, but this is the whole path from an empty org to one that runs on its own contracts.