API Basics

The StatusDashboard API is a REST API that lets you interact with your tenant programmatically. Any functionality available to your user account in the web application is available via the StatusDashboard API.

Base URL

All API requests are made to:

https://api.statusdashboard.com

Required headers

Every request must include the following headers:

You can generate and manage API keys from User Profile → API Keys in the StatusDashboard dashboard.

HTTP methods (PUT vs PATCH)

StatusDashboard uses HTTP verbs consistently:

Examples

• PUT /app/dashboards/{id}/content — every module toggle, order, and uptime setting must be included.
• PATCH /app/dashboards/{id} — update name, enabled, or other general fields without sending the full dashboard.
• PATCH /app/events/{id} — change publish, title, affectedComponents, or other event fields without resending the entire event.

Each endpoint page states whether it is full replacement or partial update. When in doubt, read the Request body table on that page.

Documented PUT exceptions (sub-resources)

These endpoints use PUT even though the body may contain a subset of fields, because they replace a single sub-resource document in one shot (not a merge across the parent event):

Workflow status transitions on the event itself use POST /app/events/{id}/timeline (new entry) or POST /app/events/{id}/reopen, not PATCH on the event root.

Response format

Successful responses return JSON with the requested data at the top level.

Endpoint errors

When your request is authenticated but rejected by the endpoint (validation, permissions, not found, etc.), the response body is JSON with an error field:

{
  "error": "Insufficient permissions."
}

Authentication failures

When authentication or tenant-level access checks fail before the endpoint runs (invalid or revoked API key, rate limit exceeded, etc.), the API returns 403 Forbidden. The response body is typically empty — do not assume a JSON error field.

HTTP status codes

Authentication and access (403)

All /app/* routes require a valid API key. When authentication or tenant-level access checks fail, the API responds with 403 Forbidden — not 401. This includes:

• Missing, malformed, or invalid API key
• Revoked API key (including keys revoked via User Profile → API Keys or user deletion)
• Per-tenant rate limit exceeded
• Disabled user or missing membership (where applicable)

Do not expect 401 for invalid or missing API keys. Rate-limited requests also return 403 Forbidden, not 429 Too Many Requests.

After authentication succeeds, endpoints may return additional 403 responses (for example, your plan does not include a feature, or your role is insufficient) with a JSON error field as shown above.

Rate limits

API requests are rate-limited per tenant. If you exceed the limit, the API rejects the request with 403 Forbidden (not 429). Limits vary by plan — check your account settings for your current limit.

Pagination

List endpoints return at most limit items per request. When more results exist, the response includes a nextToken string — a next-page bookmark. To fetch the next page, repeat the same request (same query parameters, same limit) and pass that nextToken unchanged.

Do not parse, edit, or build your own nextToken. The server uses it to resume where the previous page left off.

• nextToken is null (or omitted) when there are no more pages.
• Filters and sort order are not stored inside the token. You must send the same query parameters (dates, email filters, etc.) on every page request.

Example:

# Page 1
curl "https://api.statusdashboard.com/app/audit?limit=10" \
  -H "Authorization: Bearer bcf847abf5c6:def456"

# Page 2 — same query parameters, plus nextToken from the page-1 response
curl "https://api.statusdashboard.com/app/audit?limit=10&nextToken=eyJQSyI6Ik9SRyNhMWIyYzNkNCJ9" \
  -H "Authorization: Bearer bcf847abf5c6:def456"

Rich text fields

Several API string fields support formatted content — the same bold, italic, list, and link formatting available in the StatusDashboard web application. These fields are stored as strings and rendered on status dashboards.

Event fields that use this contract include description, impactAnalysis (incidents and maintenance only), initialTimelineMessage, timeline entry message, and post-mortem rich-text fields.

Supported formatting

• Bold and italic text
• Bullet and numbered lists
• Hyperlinks

Headings, blockquotes, and code blocks are not supported.

Accepted formats

Markdown and CommonMark syntax is not parsed. Sending **bold** or # Heading will display those characters literally, not as formatted text.

Character limits

Limits apply to the stored string length. A structured document JSON string may be longer than the visible text it contains because of JSON encoding overhead.

Integration pattern

For automation, the safest approach is to read the current value from GET, modify it, and write it back using the same encoding. This guarantees round-trip compatibility with the web application.

Rich text example

A minimal structured document containing the text "Hello, world." in bold:

"{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello, world.\",\"marks\":[{\"type\":\"bold\"}]}]}]}"

When sent in a JSON request body, the outer quotes make this a normal JSON string value.

Reports endpoints

Monthly uptime reports (admin role + uptimeReports capability):

See Get uptime report for query parameters and response shape.

Profile endpoints

See Profile in the API reference for request and response details.

Inbound webhook endpoints

Signing keys and ingest logs for the public inbound webhook (gated by the integrations entitlement):

See Ingest inbound webhook, Create webhook key, and List inbound webhook logs for field-level details.

Outbound integration endpoints

Webhook, Microsoft Teams, and Google Chat endpoints (payload destinations) and delivery hygiene (gated by the integrations entitlement). Human email, SMS, and WhatsApp subscribers stay under /app/subscribers/*.

See Create webhook endpoint and List webhook delivery logs for field-level details. Dashboard channel toggles are documented under Update subscription config (five channels required).