# 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](/api-reference).

```text
https://api.spectate.net/v1
```

## Make your first request

1. Create a [team API token](/developers/api-tokens) with the `monitors:read` ability.
2. Send it as a bearer token:

```bash
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).

| Response field | Meaning |
|---|---|
| `data` | The items on this page. |
| `current_page`, `last_page` | The page number and the number of the last page. |
| `per_page`, `total` | Items per page and the total number of items. |
| `from`, `to` | The positions of the first and the last item on this page. |

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.

```bash
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:

```json
{
  "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`.

| Status | Codes | Meaning |
|---|---|---|
| `400` | `INVALID_QUERY` | The query is not correct, for example an unknown filter or sort field. |
| `401` | `UNAUTHENTICATED`, `INVALID_TOKEN`, `TOKEN_EXPIRED` | No token, or the token is not valid, revoked or expired. |
| `403` | `FORBIDDEN`, `PLAN_LIMIT_REACHED`, `PLAN_FEATURE_UNAVAILABLE`, `TEAM_PENDING_DELETION`, `TEAM_SUSPENDED` | The token does not have the ability, the plan does not allow it, or the team is being deleted or is suspended. |
| `404` | `RESOURCE_NOT_FOUND`, `NOT_FOUND` | The resource is not in this team, or the endpoint does not exist. |
| `409` | `CONFLICT` | The request conflicts with the current state. |
| `422` | `VALIDATION_FAILED` | The request body is not valid. |
| `429` | `RATE_LIMITED` | Too many requests. See the next section. |
| `5xx` | `INTERNAL_ERROR` | A problem on our side. Try again later, with a longer wait each time. |

## 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](/api-reference/1.0.0/spectate-openapi-v1.json)
- [The API reference as one Markdown file](/api-reference.md), for AI assistants and offline reading

## Related

<CardGroup cols={2}>
  <Card title="API tokens" icon="key" href="/developers/api-tokens">
    Create tokens with only the abilities that a script needs.
  </Card>
  <Card title="API reference" icon="braces" href="/api-reference">
    Every endpoint, with examples in cURL, JavaScript, Python, PHP and Go.
  </Card>
</CardGroup>