# API

Expose a machine-readable JSON status endpoint on your dashboard.

Source: https://statusdashboard.com/docs/status-dashboards/api

> This is a plan-gated feature. If it isn't available in your account, visit the [Billing](/docs/org-mgmt/billing) page or contact support to review your options.

The public status JSON API gives integrators a stable machine-readable snapshot of live component health. Enable it when monitoring tools or internal scripts need status without parsing HTML.

***

## Enabling the API
The public status JSON API lets your end customers fetch live overall and component status without scraping the status page. When enabled, StatusDashboard serves a lean JSON document at a stable URL on **your status page host** (platform subdomain or active custom domain).

1. Open the dashboard you want to expose and go to the **API** tab (after **Widget**).
2. Toggle **Enable public status API** on.
3. Copy the public endpoint URL from the **Public endpoint** section.

The endpoint shape is:

```
https://<your-status-hostname>/api/status
```

Examples:

* Platform subdomain: `https://acme.statusdashboard.io/api/status`
* Custom domain: `https://status.yourcompany.com/api/status`

When a **custom domain is active**, use that hostname for the API. Calls to the platform subdomain return not found for `/api/status` while the custom domain is active (same consolidation as the status page).

This is **not** served from the tenant REST API host (`/app/*` with API keys). It is also separate from the [embeddable Widget](/docs/status-dashboards/widget), which uses different endpoints by design.

## Response contract
The public endpoint returns only what integrators need:

| Field                      | Description                                                                                                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `overallStatus`            | Aggregated system status (same derivation as the status page).                                                                                                             |
| `components[]`             | All components wired to the dashboard, sorted by display order (order is not returned).                                                                                    |
| `components[].id`          | Stable component UUID.                                                                                                                                                     |
| `components[].name`        | Component display name.                                                                                                                                                    |
| `components[].description` | Included only when set on the component.                                                                                                                                   |
| `components[].status`      | Live status label (for example `Operational` or an active severity label). Color and icon snapshots are not included.                                                      |
| `components[].group`       | Included only when component grouping is enabled and the component is assigned to a group. Contains `name` and optional `description` only. Group UUIDs are never exposed. |

Example:

```json
{
  "overallStatus": "All Systems Operational",
  "components": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "API Gateway",
      "description": "Public HTTPS edge",
      "status": "Operational",
      "group": {
        "name": "Core Services",
        "description": "Customer-facing production systems"
      }
    }
  ]
}
```

Success responses are pretty-printed JSON (`application/json`) so opening the URL in a browser tab is readable. Your status page also shows an **API** link in the action bar (after **Subscribe**) that opens a discovery page at `/api` with the endpoint URL and a live preview.

## Access control
Three layers gate access:

1. Your plan must include **API access**.
2. The per-dashboard toggle on the **API** tab must be on.
3. Optional **IP allowlist** (Network tab) still applies to the public endpoint.

The public status JSON API does **not** participate in [SSO](/docs/status-dashboards/sso/overview). Even when SSO protects the HTML status page, scripts and backends can call `GET /api/status` on your status page host without a Bearer token. Do not enable the API if you need all status data to stay behind SSO.

## Not a public integration API
The embeddable [Widget](/docs/status-dashboards/widget) uses separate endpoints as implementation details for the JavaScript embed. Those shapes may change with product updates and are **not** documented as a customer integration contract.

Use `GET /api/status` on your status page host for programmatic integrations.

## Security notes
Enabling the API makes component names, descriptions, group labels, and live status labels publicly fetchable (subject to your IP allowlist). No authentication credentials are required. Poll responsibly to avoid unnecessary load.

The endpoint is served with `Access-Control-Allow-Origin: *` for cross-origin `fetch` from customer applications.

White-label and custom-domain dashboards use the same host as the public status page, so the API URL matches your branded domain automatically.