REST API
Base URL: your deployment (e.g. https://app.flightbox.co). Interactive
OpenAPI reference lives at /docs on every server.
Auth, in resolution order:
1. API key — X-API-Key: fb_… or Authorization: Bearer fb_… (machines,
CI, SDKs). Get/rotate at GET /api/keys, POST /api/keys/rotate.
2. Session cookie — humans sign in via WorkOS AuthKit (/auth/login →
/auth/callback); the console and API accept the signed session.
3. Dev mode — self-hosted without WorkOS creds: requests map to the
default org. Force with FB_DEV_MODE=1.
New orgs start with $10 signup credit; when it's exhausted and billing is
not active, run launches return 402. GET /api/usage reports
credit_remaining_usd. GET /api/usage/events lists raw billing events.
PUT/DELETE /api/suites/{id} round out suite CRUD.
| Method & path | What it does |
|---|---|
GET /api/health |
liveness + dev-mode flag |
GET /api/agents |
the agent matrix with access-method metadata |
GET /api/suites · POST /api/suites |
list / create ({name, spec} or {name, yaml}) |
GET /api/suites/{id} |
suite + its batches |
POST /api/suites/{id}/run |
launch a batch: {agents?, k?, base_url?, webhook_url?} → {batch_id} |
GET /api/batches/{id} |
status, per-run results, report URL |
POST /api/batches/{id}/pdf |
render the executive PDF |
GET /artifacts/batches/{id}/… |
raw artifacts: report, replays, trace.zip, HAR, steps.jsonl, telemetry.json |
| GET /api/suites/{id}/trends | batch-over-batch series: pass rate, cost, dead clicks, failure classes |
| POST /api/orgs | self-serve org creation → {id, api_key} (tenant-isolated) |
| GET /api/usage | current-month metered usage: runs/spend by agent class, volume discount, net |
| GET /api/org · PATCH /api/org | org settings; set monthly_budget_usd (your hard stop; null = uncapped) |
| GET/POST /api/schedules · DELETE /api/schedules/{id} | Monitored Journeys: run a suite on a cadence (hourly/daily/weekly) |
Budget behavior: when net month spend reaches your cap, POST …/run returns
402 until you raise it. Infra failures are never metered.
base_url swaps the host of every task's start_url — point the same suite at
prod, staging, or a PR preview without editing tasks.