OpenAPI spec

How to use the meetbot OpenAPI 3.1 spec — Postman, Insomnia, Redoc, code generation.

The meetbot HTTP API is described as an OpenAPI 3.1.0 document. Source of truth lives at apps/web/openapi.yaml in the repo and is mirrored to:

Use it with…

Postman

File → Import → Link → https://meetbot.dev/meetbot.postman_collection.json

The collection arrives pre-folded by tag (bots, recordings, calendar, webhooks, admin). Set a collection variable bearerToken = mb_live_… and the requests authenticate automatically.

Insomnia / Bruno / Hoppscotch

Import the YAML or JSON URL above; all three handle OpenAPI 3.1 natively.

Redoc (interactive HTML)

<!doctype html>
<html>
  <body>
    <redoc spec-url="https://meetbot.dev/openapi.yaml"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>

Stoplight Elements

<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<elements-api
  apiDescriptionUrl="https://meetbot.dev/openapi.yaml"
  router="hash"
  layout="sidebar"
></elements-api>

Code generation

The spec round-trips cleanly through the major generators:

openapi-typescript → typed fetch client (the meetbot SDK already does this)
openapi-generator-cli → 50+ language clients
oapi-codegen → idiomatic Go client + server stubs

The spec covers every public HTTP endpoint the orchestrator exposes plus the outbound webhook events. Bot-side WebSocket / SSE channels (M1.1 control plane) live in their own realtime spec once that work lands.

Internal endpoints (/api/v1/ingest, /api/v1/admin/*, /webhooks/stripe) are documented for completeness but tagged separately and gated by distinct auth schemes.

Versioning

The URL prefix is /api/v1/. We will not break v1 — additive changes only. When v2 ships, the spec will publish parallel v1 + v2 surfaces for at least 6 months before v1 sunsets.

The webhook payload version is independent and tracked via the x-meetbot-webhook-version header (and the version field in v2+ envelopes). v1 webhook payloads remain accepted indefinitely; the deprecated mirror fields (failure_reason, error) are kept on v2 payloads so legacy consumers don't break.

Regeneration cadence

The spec is hand-maintained today. The intended workflow:

Engineer adds / changes a route handler under apps/orchestrator/src/routes/.
Same PR updates apps/web/openapi.yaml.
CI runs pnpm openapi:validate (swagger-cli validate) + pnpm openapi:diff (route enumeration vs spec) and fails the PR if either drifts.
On merge to main, a GitHub Action regenerates the JSON mirror + Postman collection and commits them via [skip ci].

That CI/Action work isn't built yet — see the follow-up tracker.

Reporting spec bugs

Open an issue at github.com/meetbot/meetbot with the operation id (e.g. createJob) and what's wrong. PRs editing apps/web/openapi.yaml directly are very welcome.