Prufa API v1

OpenAPI: /api/v1/openapi.json · base path: /api/v1

Quickstart

curl -X POST http://localhost:8000/api/v1/audits \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-key-1" \
  -d '{"url": "https://example.com"}'

Conventions

• All mutating endpoints accept Idempotency-Key. Replays within 24h return the original response.
• Errors are {"code": "...", "hint": "...", "docs": "..."}.
• Rate limits: free tier 5 audits/day/workspace + 50/day/IP. 429 with hint.
• Reports are public at /r/<share_token>. Unlisted, revocable, noindex.
• JSON report payload is available at /api/v1/audits/{id}/report.json.

Endpoints

• POST /audits — create a one-shot audit (anonymous, free).
• GET /audits — list recent runs in this workspace.
• GET /audits/{id} — get a run by id.
• GET /audits/{id}/report.json — get the JSON report payload.
• POST /audits/{id}/report-subscription — email the report + one 7-day re-check with a diff (anonymous, two emails total).
• POST /workspaces — create a workspace (returns the API token once).
• GET /workspaces/current — current workspace + inlined usage (auth required).
• GET /workspaces/current/usage — sync usage object (anonymous OK; auth required for paid state).
• POST /billing/checkout — create a Stripe Checkout Session (7-day trial, card-first).
• POST /billing/portal — open the Stripe Customer Portal.
• POST /billing/webhook — Stripe webhook receiver (signature-verified).
• POST /monitors — start a 1-click monitor (auth required, 402 if workspace is paused; first run is immediate, deploy-hook secret returned once).
• GET /monitors / GET /monitors/{id} — list and inspect monitors (last run status, recent runs, inline usage).
• PATCH /monitors/{id} — pause/resume (resume runs within a minute) or change cadence.
• DELETE /monitors/{id} — delete a monitor (run history kept).
• POST /monitors/{id}/run — run now (rate-capped 1/60s per monitor).
• GET /monitors/{id}/deliveries — deploy-hook delivery log + copy-paste CI snippets.
• POST /monitors/{id}/webhook/rotate — rotate the deploy-hook secret (returned once).
• POST /hooks/deploy/{monitor_id} — deploy-trigger webhook: token auth via X-Prufa-Token (no bearer), empty body valid, responds 202 {run_ids, results_url}.
• GET /healthz — liveness probe.