Copy page

Developers

Public API

Use the Spectate public API to manage your team from scripts, CI pipelines and other tools. It covers monitors, hosts, domains, projects, alerting, on-call, incidents, status pages, members and billing information. Every endpoint, with its parameters and responses, is in the API reference.

Code
https://api.spectate.net/v1

Make your first request

1. Create a team API token with the monitors:read ability.
2. Send it as a bearer token:

Code
curl https://api.spectate.net/v1/monitors \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

The response lists the monitors of the team that owns the token. To check a token and see its abilities, call GET /v1/token.

Requests and responses

• Send JSON request bodies with Content-Type: application/json. Every response is JSON, errors too.
• IDs are UUIDs. Times are ISO 8601 in UTC, for example 2026-10-25T14:03:00+00:00.
• PATCH changes only the fields that you send. To clear a field that can be empty, send null.
• The API never returns secrets that you send, such as passwords and webhook secrets.

Pagination, filters and sorting

List endpoints return pages of results. Use page (from 1) and per_page (1 to 100, default 25).

Filter with filter[name]=value. Sort with sort=field, or sort=-field for descending order. Each list endpoint in the reference shows its filters and sort fields.

Code
curl "https://api.spectate.net/v1/incidents?filter[status]=investigating&sort=-started_at" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Errors

Every error has the same shape:

Code
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Monitor not found."
  }
}

Use error.code in your code. It does not change. error.message is for people and can change. Some errors add error.details. For example, a 422 lists the invalid fields in error.details.errors.

Rate limits

Each token can send 300 requests a minute. Of these, 60 can change something (POST, PUT, PATCH and DELETE). Each response has the headers X-RateLimit-Limit and X-RateLimit-Remaining. When a token is over the limit, the API returns 429 with a Retry-After header in seconds.

Versioning

This is version 1 of the API, under /v1. In version 1, changes only add things: new endpoints, new optional request fields, new response fields and new enum values. Your code must accept fields and enum values that it does not know. A change that can break a client comes in a new version. We announce a new version before we remove the old one.

OpenAPI document

The API reference comes from an OpenAPI 3.1 document. Use it to generate a client or to import the API into a tool:

• Download the OpenAPI document
• The API reference as one Markdown file, for AI assistants and offline reading

Related