REST API

Yet Another Status Page provides a REST API for programmatic access to status data.

Base URL

https://your-status-page.com/api

Authentication

Most read endpoints are public. Write and admin operations require authentication via:

• Session cookie (from admin login)
• API key (for scripts, CI, and other non-interactive clients)

API keys

API keys are per user and use Payload’s built-in API key strategy. Requests authenticated with a key run as that user and inherit their access control.

Create a key

1. Open Admin → Users and edit (or create) a user
2. Enable Enable API Key
3. Save, then copy the generated API key — treat it like a password

Prefer a dedicated service user with the minimum role you need (editor or admin) instead of reusing a personal account.

Authenticate requests

Send the case-sensitive Authorization header in this format:

Authorization: users API-Key <your-api-key>

Example — create an incident:

curl -X POST https://your-status-page.com/api/incidents \
  -H "Authorization: users API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Elevated error rates",
    "affectedServices": [1],
    "updates": [
      {
        "status": "investigating",
        "message": "We are investigating elevated error rates."
      }
    ]
  }'

Example — fetch with JavaScript:

const response = await fetch('https://your-status-page.com/api/incidents', {
  headers: {
    Authorization: 'users API-Key YOUR_API_KEY',
  },
})

See also the Payload API key docs.

Endpoints

Incidents

List Incidents

GET /api/incidents

Query parameters:

Get Incident

GET /api/incidents/:id

Maintenances

List Maintenances

GET /api/maintenances

Query parameters same as incidents.

Get Maintenance

GET /api/maintenances/:id

Services

List Services

GET /api/services

Get Service

GET /api/services/:id

Service Groups

List Service Groups

GET /api/service-groups

Get Service Group

GET /api/service-groups/:id

Subscribers

Subscribe

POST /api/subscribe
Content-Type: application/json

{
  "type": "email",
  "email": "user@example.com"
}

Response:

{
  "success": true,
  "message": "Subscription successful"
}

Unsubscribe

POST /api/unsubscribe
Content-Type: application/json

{
  "token": "unsubscribe-token"
}

Payload REST API

The full Payload REST API is available at /api. See the Payload documentation for complete details.

Common Patterns

Filtering

GET /api/incidents?where[status][equals]=investigating

Sorting

GET /api/incidents?sort=-createdAt

Pagination

GET /api/incidents?limit=10&page=2

Field Selection

GET /api/incidents?select[title]=true&select[status]=true

GraphQL

A GraphQL endpoint is available at:

POST /api/graphql

GraphQL Playground (development only):

GET /api/graphql-playground

Rate Limiting

Public endpoints are rate limited to prevent abuse:

• 100 requests per minute per IP for read endpoints
• 10 requests per minute per IP for subscribe endpoint

Error Responses

All errors follow this format:

{
  "errors": [
    {
      "message": "Error description"
    }
  ]
}

Common HTTP status codes: