Setup walkthrough

The Getting started page is the fast path — six commands, no explanation. This is the guided version: the same journey, but with the why behind each step, the decisions you'll face, and our recommendations for getting the most out of Spec0.

By the end you'll have a team that owns an API, an AI agent that can answer questions about it, automated quality gates, a live mock, and — if you want it — a public registry others can discover.

The mental model

Three nouns explain almost everything in Spec0:

• Organisation — your company. The first person to sign up becomes the Org Owner and names the org on first run. You can belong to more than one organisation and switch between them. Billing, governance rulesets, and org-wide settings live here.
• Team — a group inside the org that owns APIs (e.g. payments, growth). Teams approve subscriptions and mint service-account tokens. An API always belongs to exactly one team.
• API — a published OpenAPI spec, versioned over time. Each version carries a quality score, a changelog, and a diff against the previous one.

Everything else — mocks, the MCP server, governance, the public registry — is a capability layered on top of those three. We'll set them up in the order you'd actually use them.

1. Create a team

APIs are owned by teams, not individuals — so the first thing to do is create the team that will own your work. A team gives you a clean ownership boundary, a place to invite collaborators, and the --team handle you'll pass to the CLI.

You can do this in the dashboard or the CLI:

spec0 team create payments

The full walkthrough — roles, invites, and verification — is in the Create a team recipe. For the role model, see Access control.

2. Install the CLI

The CLI is how specs get into Spec0. Install it globally and authenticate once:

npm install -g @spec0/cli
spec0 --version
spec0 auth login          # opens a browser, stores creds in ~/.spec0/config.json

For CI and agents, set the SPEC0_TOKEN environment variable instead of an interactive login — see step 6.

3. Publish your first API

From a directory containing your openapi.yaml:

spec0 init                                  # detect the spec, write .spec0.yaml
spec0 push openapi.yaml --team payments     # publish, team-scoped & private

spec0 init writes a .spec0.yaml config that records which spec to publish and under which team — commit it so the same settings apply everywhere. spec0 push uploads the spec, computes a version, runs the lint, and produces a diff against the previous version.

How the version is chosen: spec0 push reads the spec's info.version. Add --semver to auto-bump the patch component when the last version is valid semver, or --version <tag> to pin one explicitly. Re-pushing identical content is a no-op. The full model is in Versioning.

4. Connect an AI agent

This is where Spec0 starts paying off. Spec0 runs an MCP server so your coding agent can search and read your org's APIs directly — no copy-pasting specs into a chat window. The CLI writes the client config for you:

spec0 mcp install            # auto-detect Cursor / Claude / VS Code, write config
spec0 mcp url                # or print the endpoint to wire up manually

Because you're logged in, mcp install includes your auth header, so the org-scoped tools light up immediately. Restart your client and the Spec0 tools appear.

If you'd rather configure it by hand, point your client at https://api.spec0.io/mcp:

{
  "mcpServers": {
    "spec0": {
      "url": "https://api.spec0.io/mcp"
    }
  }
}

claude mcp add --transport http spec0 https://api.spec0.io/mcp

{
  "servers": {
    "spec0": {
      "type": "http",
      "url": "https://api.spec0.io/mcp"
    }
  }
}

These are the tools your agent gets once connected:

Ask it something

Restart your client and try prompts like these — each maps to a tool above:

• "Which of our APIs handles refunds, and what do I send to issue one?"
• "List every endpoint in the payments API that creates a resource."
• "What changed in the orders API between the last two versions? Anything breaking?"
• "Generate a typed client for the createCharge operation."
• "Who owns the inventory API and what's its current quality score?"

The agent searches your registry, reads the exact spec, and answers against your APIs — not a hallucinated guess. See API discovery for how this works under the hood.

5. Set governance rules at the org level

Now make quality automatic. Spec0 governance is built on Spectral rulesets — a set of lint rules every spec is checked against. Define the ruleset once at the org level and every team inherits it.

Go to Settings → API governance and either start from the Spec0 default ruleset or paste your own. Rules can require descriptions on every operation, ban additionalProperties: true, enforce naming conventions, mandate error response schemas — anything Spectral can express.

Each API version then gets a quality score (the percentage of rules it passes), surfaced on the dashboard and via the MCP get_api_health tool. See Governance for the ruleset format and scoring.

6. Add quality gates with Spectral lint

Governance is only as good as its enforcement. Run the same ruleset in CI so a spec that drops below your bar fails the PR instead of silently landing:

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

• --org-ruleset uses the ruleset you defined in step 5 (not just the spec-local one).
• --min-score 80 fails (exit code 7) if the quality score drops below 80.
• --strict treats warnings as errors.

Wire it into GitHub Actions alongside the publish step — this is the git-native flow we recommended in step 3:

name: Spec0
on:
  push:
    branches: [main]
    paths: ['openapi.yaml']
  pull_request:
    paths: ['openapi.yaml']
jobs:
  spec0:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @spec0/cli
      - run: spec0 lint openapi.yaml --org-ruleset --min-score 80 --strict
      - run: spec0 push openapi.yaml --team payments --semver
        if: github.ref == 'refs/heads/main'
        env:
          SPEC0_TOKEN: ${{ secrets.SPEC0_TOKEN }}
          SPEC0_ORG_ID: ${{ secrets.SPEC0_ORG_ID }}

spec0 ci generate github scaffolds this for you. To also block breaking changes, add spec0 diff --breaking-only — see the block-on-breaking-changes recipe and the full CI guide.

7. Spin up a mock

Every published spec can back a live mock server — no code, no infrastructure. Useful for frontend work before the backend exists, for integration tests, and for letting consumers try an API before you build it:

spec0 mock create --api my-api    # provision a mock (one-time key on first run)
spec0 mock url my-api             # print the base URL

Point your app at that URL and hit any path in the spec — you get realistic responses generated from the schema, always serving the latest published version. For response variants, conditional responses (CEL), and request validation, see Mock server.

8. Where the registry pays off

Once a few APIs are in the registry with governance and MCP connected, the use cases stack up:

Example prompts once your registry is populated

• "I'm building a checkout page — which of our APIs do I need and in what order do I call them?"
• "Find every API that touches PII and tell me which ones are missing an auth scheme."
• "The orders API just bumped a major version — what broke and which of my calls need to change?"
• "Scaffold a TypeScript SDK for the three payments operations I use most."

9. Open an API to the public registry

Everything so far has been private to your org. When an API is stable and you want others — partners, customers, the public — to discover and integrate it, publish it:

spec0 publish openapi.yaml --semver

This registers the API to the public registry with a shareable URL. Anyone can browse the spec, read the docs, and point the public MCP server at it for discovery. The same versioning, changelog, and quality score follow it to the public side. Keep publishing the same way (or via CI) and the public version tracks your latest.

What's next

• Concepts — the full mental model: registry, specs, versions, mocks, governance.
• CLI reference — every command and the workflow guides.
• Agents & MCP — go deeper on letting agents work over your registry.
• Recipes — focused, task-sized guides (teams, tokens, subscriptions).