API reference

Every REST endpoint the API serves, grouped the way .spec/plan/03-api.md specifies them.

Base URL and auth

Every path below is relative to https://api.burnratesurgeon.io/api/v1. The version is in the path, not a header — /api/v1/ stays stable while the API grows. A request authenticates with either an Auth0 JWT (the browser session) or a brs_ API token scoped to replay:write or corpus:read (the CLI and the PR-gate GitHub Action). See Webhooks for the one endpoint that authenticates differently, and MCP server for the corpus served to AI agents over JSON-RPC rather than plain REST.

Terminal

curl https://api.burnratesurgeon.io/api/v1/corpus/stats

Identity

PLAN-API-01

Method	Path	Auth	What it does
`GET`	`/users/me`	JWT	The signed-in user and their org memberships.
`POST`	`/users/sync`	JWT	Create or update the local user row on the first call after an Auth0 login.
`GET`	`/users/me/export`	JWT	GDPR Art. 15/20 export: account, memberships and API token metadata.

Organizations

PLAN-API-02

Method	Path	Auth	What it does
`GET`	`/orgs`	JWT	Organizations the caller is a member of.
`POST`	`/orgs`	JWT	Create an organization; the creator becomes its owner.
`GET`	`/orgs/:orgId`	JWT · member	One organization.
`PATCH`	`/orgs/:orgId`	JWT · owner\|admin	Update the name or the corpus consent level.
`GET`	`/orgs/:orgId/members`	JWT · member	List the organization’s members.
`POST`	`/orgs/:orgId/members`	JWT · owner\|admin	Invite a member by email and role.

API tokens

PLAN-API-03

Method	Path	Auth	What it does
`GET`	`/orgs/:orgId/tokens`	JWT · owner\|admin	List tokens by prefix only — the plaintext is never stored.
`POST`	`/orgs/:orgId/tokens`	JWT · owner\|admin	Mint a brs_ token; the plaintext is shown exactly once.
`DELETE`	`/orgs/:orgId/tokens/:tokenId`	JWT · owner\|admin	Revoke a token (sets revoked_at).

TSDB snapshots

PLAN-API-04

Method	Path	Auth	What it does
`POST`	`/orgs/:orgId/snapshots`	JWT or brs_ token · replay:write	Register a snapshot and get a signed R2 upload URL.
`POST`	`/orgs/:orgId/snapshots/:snapshotId/complete`	replay:write	Mark the upload done and trigger indexing.
`GET`	`/orgs/:orgId/snapshots`	JWT · member	List snapshots, filterable by vendor and status.
`GET`	`/orgs/:orgId/snapshots/:snapshotId`	JWT · member	One snapshot.

Rule sets

PLAN-API-05

Method	Path	Auth	What it does
`POST`	`/orgs/:orgId/rule-sets`	replay:write	Submit rules.yml (+ alertmanager.yml); idempotent by checksum, PromQL-validated.
`GET`	`/orgs/:orgId/rule-sets/:ruleSetId`	JWT · member	One rule set.

Replay runs

PLAN-API-06

Method	Path	Auth	What it does
`POST`	`/orgs/:orgId/replays`	replay:write	Queue a replay (one_shot \| shadow_continuous \| pr_gate); idempotent by input checksum.
`GET`	`/orgs/:orgId/replays`	JWT · member	List replay runs, filterable by status and mode.
`GET`	`/orgs/:orgId/replays/:replayId`	JWT · member	The run plus its classifications.
`GET`	`/orgs/:orgId/replays/:replayId/alerts`	JWT · member	Simulated alerts: alertname, labels, fireTime, wouldPage, silencedBy.
`GET`	`/orgs/:orgId/replays/:replayId/report`	JWT · member	Classified report; `Accept: text/markdown` returns the same report the CLI and PR comment use.

Classifier

PLAN-API-07

Method	Path	Auth	What it does
`POST`	`/orgs/:orgId/replays/:replayId/classify`	replay:write	Re-run the hybrid classifier (rule-based + corpus nearest-signature) synchronously.

Corpus

PLAN-API-08

Method	Path	Auth	What it does
`GET`	`/corpus/signatures`	optional	Public signatures unless authenticated; filterable by class and vendor.
`GET`	`/corpus/signatures/:signatureKey`	optional	One signature; 404 when private and the caller does not own it.
`POST`	`/corpus/search`	optional	Semantic search over signatures (Vectorize) — the same contract `search_signatures` uses over MCP.
`GET`	`/corpus/stats`	none	Anonymous counters over public signatures only — cacheable, never scoped by session.

Payments & billing

PLAN-API-BILLING

Method	Path	Auth	What it does
`POST`	`/payments/checkout`	JWT	Start a billing-gateway checkout for a plan.
`POST`	`/payments/portal`	JWT	Open the billing-gateway customer portal.
`GET`	`/orgs/:orgId/billing`	JWT	Plan, subscription and invoices; degrades to plan-only if the gateway is down.
`GET`	`/orgs/:orgId/billing/invoices/:id/pdf`	JWT	One invoice as a PDF.

Dashboard

PLAN-API-10

Method	Path	Auth	What it does
`GET`	`/orgs/:orgId/dashboard/stats`	JWT · member	North-star and supporting counts: replays, correctly predicted critical alerts, classification breakdown.

Error shape

Every error response — from any endpoint above — has the same shape:

Error response

{
  "error": {
    "code": "ERR_NOT_FOUND",
    "message": "Replay run not found",
    "field": null,
    "details": {}
  }
}