REST API v1

The REST API v1 manages incidents and reads status for your pages. Every address is under https://statuspagebuilder.com/api/v1 and answers JSON. API access is included on Pro and Business; see pricing.

Authentication

Create an API key in your dashboard. The key is shown once when created, so copy it at that time. Send it on every request as Authorization: Bearer <key>.

Only the hash of a key is stored. A missing key, a key that was never issued and a revoked key all answer the same 401, so a guess learns nothing. Keys belong to one account: they see that account's pages and no one else's.

Rate limit

60 requests a minute per key, in fixed one minute windows. Past the limit the answer is 429 with a Retry-After header. A 429 is a request that was refused before it was served: it is never counted against usage.

Endpoints

POST /api/v1/incidents creates a manual incident.
POST /api/v1/incidents/{id}/updates adds an update to an incident.
GET /api/v1/pages/{id}/status reads the public status view for a page.

Create a manual incident

Create a manual incident for unplanned outages. The incident opens on the specified components with the given status.

curl -X POST https://statuspagebuilder.com/api/v1/incidents \\
  -H "Authorization: Bearer sk_your_key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "pageId": "clz8k4m2p0000abcd1234efgh",
    "title": "Database connectivity issues",
    "componentIds": ["comp-abc123", "comp-def456"],
    "status": "investigating"
  }'

The body requires pageId (the page the incident belongs to), title, and componentIds (an array of component ids). Optional status defaults to investigating. Valid statuses are investigating, identified, monitoring, and resolved.

Response, 201:

{
  "id": "inc-clz8k4m2p0000qrst9012uvwx"
}

Add an incident update

Add a status update to an existing incident. This is how you communicate progress to subscribers.

curl -X POST https://statuspagebuilder.com/api/v1/incidents/inc-clz8k4m2p0000qrst9012uvwx/updates \\
  -H "Authorization: Bearer sk_your_key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "status": "identified",
    "body": "We have identified the issue and are working on a fix."
  }'

The body requires status and body. The status must be one of investigating, identified, monitoring, or resolved.

Response, 201: empty body.

Read page status

Get the public status view for a page. Returns the same data shape as the public status.json endpoint.

curl https://statuspagebuilder.com/api/v1/pages/clz8k4m2p0000abcd1234efgh/status \\
  -H "Authorization: Bearer sk_your_key"

Response, 200:

{
  "page": {
    "slug": "my-service",
    "title": "My Service Status",
    "logoUrl": "https://example.com/logo.png",
    "brandColor": "#0066cc"
  },
  "overall": "operational",
  "components": [
    {
      "name": "API",
      "state": "operational",
      "uptime90": 99.5
    },
    {
      "name": "Dashboard",
      "state": "degraded",
      "uptime90": 95.2
    }
  ],
  "activeIncidents": [
    {
      "id": "inc-clz8k4m2p0000qrst9012uvwx",
      "title": "Database connectivity issues",
      "status": "investigating",
      "startedAt": "2026-10-15T14:30:00.000Z",
      "updates": [
        {
          "status": "investigating",
          "body": "We are investigating reports of database issues.",
          "at": "2026-10-15T14:30:00.000Z"
        }
      ]
    }
  ],
  "maintenance": []
}

overall is one of operational, partial outage, major outage, or under maintenance. state for each component is one of operational, degraded, or down. uptime90 is the percentage over the last 90 days, or null if there is no data.

Error responses

An error is always a JSON object with a plain error sentence:

{
  "error": "Page not found"
}

400 the body is missing a required field or names an invalid value.
401 the key is missing, unknown or revoked.
403 the account's plan does not include the API: the REST API is on Pro and Business.
404 no such page or incident, or it does not belong to the account.
429 the key passed 60 requests in the current minute. Carries Retry-After header.

How to read status.json

The public status page at /s/{slug}exposes /api/public/{slug}/status.json. The JSON has the same shape as the v1 pages/{id}/status response: page, overall, components, activeIncidents, and maintenance. This endpoint requires no authentication and is the recommended way to embed status on another site.