API Reference
HTTP API for the meetbot orchestrator. OpenAPI 3.1 spec, Postman collection, endpoint table.
The complete HTTP API reference is published as an OpenAPI 3.1.0 spec served straight from this site.
| Format | URL |
|---|---|
| OpenAPI YAML | /openapi.yaml |
| OpenAPI JSON | /openapi.json |
| Postman collection | /meetbot.postman_collection.json |
Drop the YAML / JSON URL into Insomnia, Postman, Bruno, Stoplight, or
Redoc to get an interactive client. The Postman collection is
pre-folded by tag (bots, recordings, calendar, webhooks,
admin).
Endpoints
| Method | Path | Tag | Purpose |
|---|---|---|---|
POST | /api/v1/jobs | bots | Create + dispatch a meeting bot |
GET | /api/v1/jobs/{id} | bots | Fetch a job by id |
DELETE | /api/v1/jobs/{id} | bots | Cancel a job |
POST | /api/v1/jobs/{id}/request-recording-permission | bots | Ask the host for explicit consent |
POST | /api/v1/intake/calendar-invite | calendar | Receive a parsed calendar invite (worker → orchestrator) |
POST | /api/v1/ingest | ingest | Bot lifecycle ingest (orchestrator-internal) |
POST | /api/v1/cli-auth/init | cli-auth | Mint a device-flow nonce |
POST | /api/v1/cli-auth/poll/{nonce} | cli-auth | Poll for device-flow completion |
POST | /api/v1/cli-auth/complete | cli-auth | Finalize device-flow auth |
GET | /api/v1/admin/host | admin | Host metrics + bot counts (operator-only) |
POST | /webhooks/stripe | admin | Stripe webhook receiver (operator-only) |
GET | /healthz | admin | Liveness probe |
Webhook events
Outbound events the orchestrator POSTs to consumer-supplied URLs. v2
payloads always carry version: 2 plus a failure_code enum on
failure transitions; v1 payloads omit the version field and carry the
legacy free-text failure_reason only.
| Event | When | Notes |
| ----------------------------------- | ------------------------------------------ | ------------------------------------------------ | ------ |
| job.status_changed | every status transition | most events you'll handle |
| job.finalized | manifest written | exactly once per successful job |
| job.failed | terminal failed | always carries failure_code in v2 |
| bot.recording_permission_response | host responded to the consent verb | granted: true | false |
| bot.competing_bot_detected | spotted Otter / Fireflies / Read in roster | leftMeeting reflects autoLeave.onBotDetected |
See the webhook verification guide for
HMAC signing + dedupe via deliveryId.
Authentication
Send your meetbot API key as a Bearer token:
GET /api/v1/jobs/5c3e9d8a-7c4e-4d11-b2cb-9d6e0c5e1234 HTTP/1.1
Host: api.meetbot.dev
Authorization: Bearer mb_live_...Issue + rotate keys in the dashboard. Revoked keys 401 immediately.
Spec lifecycle
The spec at apps/web/openapi.yaml is the source of truth. Today it's
hand-maintained against apps/orchestrator/src/server.ts and the Zod
schemas in apps/orchestrator/src/routes/. A future CI job will diff
the route table on every PR and fail when the spec drifts — see
/docs/api-reference/openapi for the
proposed regeneration cadence.