Spectate API

Manage your Spectate team from code: monitors, hosts, domains, projects, alerting, on-call, incidents and status pages. This API backs the official SDKs and the Terraform provider; everything they do, you can do with plain HTTP.

Authentication

Every request sends a team API token as a bearer token:

Code
GET /v1/token HTTP/1.1
Host: api.spectate.net
Authorization: Bearer spct_…

Owners and managers create tokens in the dashboard under Team → API tokens. A token:

• belongs to the team, not to the member who created it, and keeps working when that member leaves;
• can only do what its abilities allow, for example monitors:read or incidents:write. Each endpoint lists the ability it requires. There is no wildcard: a token never gains an ability it wasn't created with;
• is shown once. Spectate stores only a hash of it; lost tokens can't be recovered, only regenerated or revoked;
• may expire. Revoked and expired tokens stop working immediately.

Tokens look like spct_ followed by 46 letters and digits, the last 6 of which are a checksum, so secret scanners can recognise them. Call GET /v1/token to check a token and see its abilities.

Requests and responses

• Send and expect JSON. Request bodies are application/json; responses are always JSON, also for errors.
• IDs are UUIDs. Timestamps are ISO 8601 in UTC, for example 2026-10-25T14:03:00+00:00.
• PATCH changes only the fields you send. Fields you leave out keep their value; send null to clear a nullable field.
• Secrets you send (passwords, webhook secrets) are never returned.

Pagination

List endpoints are paginated with page (from 1) and per_page (1–100, default 25). The response has the items in data, plus current_page, last_page, per_page, total, from, to and the URLs of the neighbouring pages. Filters use filter[name]=value; sorting uses sort=field (ascending) or sort=-field (descending).

Errors

Every error has the same shape:

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

Branch on error.code, which is stable; error.message is for people and may change. Some codes add error.details. Validation errors (422, VALIDATION_FAILED) list the invalid fields in error.details.errors.

Rate limits

Each token may make 300 requests a minute, of which 60 may change something (POST, PUT, PATCH, DELETE). Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; when you're over, the API answers 429 with a Retry-After header in seconds.

Versioning

This is version 1, under /v1. Within it, changes are additive only: new endpoints, new optional request fields, new response fields and new enum values. Treat unknown fields and enum values as possible. Anything that would break a client gets a new version, announced well before the old one is retired.