API overview
REST v1 base URL, core resources, automation flows, and response envelopes for CI and agents.
API reference
PreFlight API v1
The public API lets CI pipelines, deploy hooks, status pages, and AI agents read project health and trigger checks without opening the dashboard. Every route is account-scoped, rate-limited, and designed for automation.
Use bearer API keys created by a workspace owner. Keys start with pf_live_ and are shown once at creation. PreFlight stores only a SHA-256 hash plus a short prefix after that.
Base URL
https://getpreflight.dev/api/v1
Self-hosted or preview deployments can use your own origin. MCP and SDK clients accept PREFLIGHT_API_URL for the same purpose.
Authentication
/projectsList every project the key can access. Useful for discovering project UUIDs in CI.
All authenticated routes expect:
Authorization: Bearer pf_live_...
Content-Type: application/json
See API authentication for scope, idempotency, and rate-limit behavior.
Core resources
| Resource | Methods | Purpose |
|---|---|---|
| Projects | GET /projects | Discover project UUIDs and workspace ownership. |
| Checks | POST /projects/:id/checks | Run the full pre-flight suite and return probe rows. |
| Check run | GET /projects/:id/checks/:runId | Poll a specific run until completion. |
| Status | GET /projects/:id/status | Compact Sentinel summary for bots and status pages. |
| Incidents | GET /projects/:id/incidents | Open incidents plus recent failures (7-day window). |
| Deploy gate | GET /projects/:id/deploy-gate | Hard allow/deny signal for CI and Vercel. |
| Uptime | GET /projects/:id/uptime | SLA percentages and consecutive success streaks. |
| Activity | GET /projects/:id/activity | Audit-style event log for checks, gates, and settings. |
| Report | GET /projects/:id/report | Structured launch report for exports and bots. |
| Schema sync | GET /projects/:id/schema-sync | Supabase migration drift signal for deploy gates. |
Typical automation flows
Pre-deploy gate. Call
GET /deploy-gatein strict mode before promoting a Vercel deployment or merging to main.Post-deploy check.
POST /checkswith anIdempotency-Key, then poll/checks/:runIduntil the run finishes.Status page bot. Poll
/statusand/uptimeon a schedule; surface open incidents from/incidents.Agent workflow. Connect the MCP server so Cursor, Claude Desktop, or other MCP hosts can trigger checks and read gate state in natural language.
Response shape
Successful check runs return a normalized envelope:
{
"runId": "uuid",
"status": "success",
"summary": "All connected providers passed.",
"counts": { "success": 12, "warning": 0, "failed": 0 },
"results": [
{
"integrationType": "stripe",
"probeKey": "stripe_webhook_signature",
"status": "success",
"message": "Signed test event accepted.",
"responseTimeMs": 142,
"fixSuggestion": null
}
]
}
Deterministic first
AI diagnosis may appear on check responses when enabled, but automation should rely on status, counts, and per-probe rows. Those fields are always derived from stored probe results.