API reference

LiveStatus exposes a REST API for every action you can take in the dashboard. Use it to post incidents from your monitoring pipeline, sync services from your infrastructure-as-code, or build custom integrations.

Generating an API key

API keys are a Pro+ feature. To create one:

1. Go to Dashboard → Account.
2. Scroll to the API Keys section and click New key.
3. Give the key a name (e.g. Production CI) and pick the organization it should belong to.
4. Copy the key shown in the dialog — this is the only time you will ever see it. Store it in your secrets manager immediately.

Keys look like ls_live_<32 chars>. Revoke a key at any time from the same screen; revocation is immediate.

Authentication

Every request must include the key in one of two headers:

# Preferred — standard bearer scheme
Authorization: Bearer ls_live_abc123...

# Fallback — convenient for quick curl tests
X-API-Key: ls_live_abc123...

Keys are scoped to a single organization. Attempting to access resources in another org will return 404 not_found — the API never reveals the existence of cross-org data.

Base URL

https://<your-domain>/api/v1

Endpoints

Status pages

• GET /api/v1/pages — list pages in the organization
• POST /api/v1/pages — create a page. Body: { name, slug, description?, brandColor? }
• GET /api/v1/pages/{pageId} — fetch a single page
• PATCH /api/v1/pages/{pageId} — update. Body: any of name, slug, description, brandColor, isPublic
• DELETE /api/v1/pages/{pageId} — permanently delete

Services

• GET /api/v1/pages/{pageId}/services — list services on a page
• POST /api/v1/pages/{pageId}/services — create. Body: { name, monitorUrl?, currentStatus?, displayOrder? }
• PATCH /api/v1/services/{serviceId} — update. Typical use: { "currentStatus": "degraded" }

Valid currentStatus values: operational, degraded, outage, maintenance.

Incidents

• POST /api/v1/pages/{pageId}/incidents — open an incident. Body:

  {
    "title": "API latency spike",
    "impact": "major",
    "status": "investigating",
    "body": "We are seeing elevated p99 latency on the payments API.",
    "affectedServiceIds": ["<uuid>"]
  }
  

  Valid impact: minor, major, critical. Valid status: investigating, identified, monitoring, resolved.
• POST /api/v1/incidents/{incidentId}/updates — append an update. Body: { body, status? }. Setting status: "resolved" closes the incident and stamps resolvedAt.

Example — post an incident from GitHub Actions

curl -X POST "https://status.example.com/api/v1/pages/$PAGE_ID/incidents" \
  -H "Authorization: Bearer $LIVESTATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deployment rollback in progress",
    "impact": "minor",
    "status": "monitoring",
    "body": "Rolling back web-app to v2.41.0 due to a regression."
  }'

Rate limits

Every key is limited to 60 requests per minute. Responses carry the usual headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1712764800

If you exceed the limit, you'll get 429 rate_limited. Back off until the X-RateLimit-Reset timestamp (unix seconds).

Error format

All errors use a consistent shape:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid, expired, or revoked."
  }
}

Common codes:

Security notes

• Treat API keys like passwords — never commit them to source control.
• Use a dedicated key per environment (e.g. Production CI, Staging Deploy) so you can revoke one without disrupting others.
• LiveStatus only stores a SHA-256 hash of the key. If you lose it, you'll need to generate a new one.

Ad creative generator

GET /api/og/ad returns a branded PNG suitable for social posts, Google Ads, Reddit, LinkedIn, email signatures, and anywhere else you need an image URL. It's public and unauthenticated.

Variants: og (1200x630), square (1080x1080), story (1080x1920), linkedin (1200x627), reddit (1200x630), pinterest (1000x1500), google-square (1200x1200), google-portrait (960x1200), hero (1920x1080).

# Open Graph card
https://livestatus.dev/api/og/ad?headline=Status+pages+that+actually+get+seen

# Instagram square with custom accent
https://livestatus.dev/api/og/ad?headline=Ship+in+minutes&variant=square&accent=%236366f1

# LinkedIn post, light theme
https://livestatus.dev/api/og/ad?headline=Migrate+from+Statuspage&variant=linkedin&theme=light