API reference

Status and incidents

Read-only API endpoints expose a project's live health to systems outside PreFlight — status pages, Slack bots, CI badges, PagerDuty/OpsGenie pipelines, and custom dashboards. All routes require a bearer API key and are rate limited per key and per project.

Poll status and incidents safely between deploys. To trigger a new check or block a release, use POST /checks and GET /deploy-gate instead.

Authentication

Authorization: Bearer pf_live_...

See API authentication for key creation, scopes, and rate limits.

---

Project status

Compact health summary: latest check, seven-day uptime, Uptime Monitoring state, active incidents, and connected-provider statuses.

{
  "project_id": "uuid",
  "project_name": "vibecoder-saas",
  "evaluated_at": "2026-05-31T12:00:00.000Z",
  "overall_status": "healthy",
  "latest_check": {
    "id": "uuid",
    "status": "success",
    "summary": "All connected checks passed.",
    "started_at": "2026-05-31T11:58:00.000Z",
    "completed_at": "2026-05-31T11:58:04.000Z",
    "run_mode": "standard",
    "trigger_source": "api"
  },
  "uptime": {
    "seven_day_percentage": 99.94,
    "total_samples": 1008,
    "successful_samples": 1007,
    "avg_response_time_ms": 212
  },
  "Uptime Monitoring": {
    "enabled": true,
    "paused": false,
    "last_status": "success",
    "last_sampled_at": "2026-05-31T11:55:00.000Z"
  },
  "incidents": { "active_count": 0 },
  "integrations": {
    "connected_count": 6,
    "failing_count": 0,
    "providers": [
      {
        "type": "stripe",
        "last_status": "success",
        "last_tested_at": "2026-05-31T11:58:02.000Z"
      }
    ]
  }
}

Overall status values

| Value | Meaning | | --- | --- | | `healthy` | Latest check passed, no failing providers, no active incidents | | `degraded` | Latest check warned, or something needs review but nothing is hard-failing | | `failing` | Latest check failed or a connected provider is failing | | `unknown` | No check run exists yet for this project |

Use overall_status for traffic-light badges. Drill into /incidents and /checks/:runId when it is not healthy.

---

Incidents and failures

Active and recent incidents from recovery guide state plus failed/warning results from the last seven days.

Query parameters

| Param | Behavior | | --- | --- | | `status` | Filter incidents: `open`, `acknowledged`, `resolved`, or `dismissed` | | `limit` | Max results per section. Default 25, max 100 |

{
  "project_id": "uuid",
  "summary": {
    "open_incidents": 1,
    "acknowledged_incidents": 0,
    "recent_failures_7d": 3
  },
  "incidents": [
    {
      "id": "uuid",
      "key": "stripe-webhook-delivery",
      "status": "open",
      "updated_at": "2026-05-31T10:00:00.000Z"
    }
  ],
  "failures": [
    {
      "id": "uuid",
      "integration_type": "stripe",
      "probe_key": "stripe_webhook_delivery",
      "status": "failed",
      "error_message": "401 Unauthorized",
      "fix_suggestion": "Rotate STRIPE_WEBHOOK_SECRET to match the deployed endpoint.",
      "response_time_ms": 480,
      "created_at": "2026-05-31T09:58:00.000Z"
    }
  ]
}

The failures array surfaces recent probe rows even when no formal incident record exists — useful for bots that need the latest error message and fix suggestion.

---

release rule

Hard allow/deny signal for CI and Vercel. Returns 200 when allowed, 409 when blocked.

This endpoint shares the same evaluation engine as the dashboard Release Rules surface. Policy options, strict vs relaxed mode, and CI examples are in the Release Rules guide.

---

Related read endpoints

| Endpoint | Purpose | | --- | --- | | `GET /projects/:id/uptime` | SLA percentages and consecutive success streaks | | `GET /projects/:id/activity` | Audit-style log for checks, gates, and settings | | `GET /projects/:id/report` | Structured launch report for exports and bots | | `GET /projects/:id/schema-sync` | Supabase migration drift for Release Rules |

See API overview for the full resource list.

Polling guidance

| Consumer | Suggested cadence | Endpoints | | --- | --- | --- | | Public status page | 1–5 minutes | `/status`, `/uptime` | | On-call bot | 1 minute during incidents | `/incidents?status=open` | | CI badge | After each deploy | `/status` once | | Deploy pipeline | Once per promote | `/deploy-gate` | Status and incidents are GET requests. They do not mutate project state. Stay within per-key and per-project rate limits. To run a fresh check, call POST /projects/:id/checks with an Idempotency-Key.

Rate limits

release rule, status, and incidents routes each enforce separate buckets (typically 60–120 requests per minute per key/project). Exceeding limits returns 429 with retry guidance in response headers.

<RelatedLinks links={[ { href: "/docs/api/overview", title: "API overview", description: "Full v1 resource catalog." }, { href: "/docs/api/authentication", title: "API authentication", description: "Keys, scopes, and idempotency." }, { href: "/docs/guides/deploy-gates", title: "Release Rules", description: "Policy tuning and CI wiring." }, { href: "/docs/guides/trust-center", title: "Trust Center", description: "Customer-facing pages fed by the same probe data." }, ]} />