Status and incidents API
Read-only project status, incidents, and deploy-gate endpoints for status pages, bots, and CI.
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
/api/v1/projects/:projectId/statusCompact health summary: latest check, seven-day uptime, Sentinel 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
},
"sentinel": {
"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
/api/v1/projects/:projectId/incidentsActive and recent incidents from runbook 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.
Deploy gate
/api/v1/projects/:projectId/deploy-gate?mode=strictHard allow/deny signal for CI and Vercel. Returns 200 when allowed, 409 when blocked.
This endpoint shares the same evaluation engine as the dashboard Deploy Gates surface. Policy options, strict vs relaxed mode, and CI examples are in the Deploy Gates 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 deploy gates |
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 |
Read-only and safe to poll
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
Deploy gate, 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.