API reference

API authentication

PreFlight public API v1 uses bearer account API keys. Keys are created by the workspace owner from Dashboard → Settings → API keys and inherit that owner's project access.

Browser sessions continue to use Supabase Auth and workspace-aware RLS. Automation, CI, status bots, and the MCP server use API keys exclusively.

Create a key

Open Settings → API keys as a workspace owner. Name the key for its purpose (for example github-actions-deploy-gate). Copy the raw key immediately. PreFlight shows it once, then stores only a SHA-256 hash and prefix. Store the key in your CI secret manager or MCP host configuration — never commit it to git.

Header format

Every authenticated request must include:

Authorization: Bearer pf_live_...
Content-Type: application/json

Keys must match the pattern pf_live_ followed by at least 32 alphanumeric characters.

Scope and access

| Rule | Behavior | | --- | --- | | Ownership | Keys belong to the creating user account | | Project access | Limited to projects that user can control in the workspace | | Rotation | Create a new key, update consumers, then revoke the old key | | Browser | Dashboard routes do not accept API keys; use Supabase session cookies |

Idempotent writes

Retried POST requests — especially check triggers from CI — should send a stable idempotency header:

Idempotency-Key: ci-run-2026-06-13-main-001

PreFlight deduplicates on that key so a network retry does not spawn duplicate check runs.

Rate limiting

| Limit type | Behavior | | --- | --- | | Per-key throughput | Applied on all `/api/v1/*` routes | | Per-project checks | Additional guardrails on expensive check triggers | | Failed auth | Independently rate limited from successful traffic | | Payload size | Oversized JSON bodies rejected before deeper processing |

When limited, the API returns 429 with retry guidance. Automation should backoff exponentially.

Core endpoints

List projects visible to the key. Use this to discover UUIDs in CI. Trigger a full pre-flight run. Returns `runId`, aggregate status, and probe rows. Poll a specific run until probes finish. Evaluate deploy readiness. Returns `allowed` and blocking reasons.

See the full catalog in the API overview.

Example: trigger a check

curl -X POST \
  -H "Authorization: Bearer pf_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-run-2026-06-13-001" \
  https://getpreflight.dev/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/checks

Example response

{
  "runId": "8b3f2c1a-9d4e-4f5a-b6c7-1234567890ab",
  "status": "warning",
  "summary": "11 passed, 1 warning, 0 failed.",
  "counts": { "success": 11, "warning": 1, "failed": 0 },
  "results": []
}

Treat API keys like production secrets. Scope CI keys to deploy-gate and check routes only by rotating keys when personnel change.

<RelatedLinks links={[ { href: "/docs/api/overview", title: "API overview", description: "All v1 resources and automation patterns." }, { href: "/docs/api/mcp-server", title: "MCP server", description: "Use the same key from Cursor or Claude Desktop." }, { href: "/docs/guides/deploy-gates", title: "Release Rules", description: "Wire gate responses into CI." }, ]} />