APITutorial

API overview

REST v1 resources, response envelopes, and automation flows.

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

List 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 Uptime Monitoring summary for bots and status pages. | | Incidents | `GET /projects/:id/incidents` | Open incidents plus recent failures (7-day window). | | release rule | `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. | | Database Change Check | `GET /projects/:id/schema-sync` | Supabase migration drift signal for Release Rules. |

Typical automation flows

Pre-release rule. Call GET /deploy-gate in strict mode before promoting a Vercel deployment or merging to main. Post-deploy check. POST /checks with an Idempotency-Key, then poll /checks/:runId until the run finishes. Status page bot. Poll /status and /uptime on a schedule; surface open incidents from /incidents. Agent workflow. Connect the [MCP server](/docs/api/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
    }
  ]
}

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.