# REST API

> Authentication, scopes, conventions and every /api/v1 endpoint.

Everything the app does goes through `https://pulse.nightroll.app/api/v1`.

## Authentication

Create an API key in **Settings → API keys** and send it as a bearer token:

```sh
curl https://pulse.nightroll.app/api/v1/checks -H "Authorization: Bearer nr_pulse_..."
```

A key belongs to you and one org, has scopes (`read`, `write`, `admin`; never more than your role allows) and an optional expiry. It stops working when you leave the org. These are not ingest keys: [OTLP ingest](/docs/otlp-ingest/) uses `pulse_ik_...` keys.

## Conventions

- JSON in and out. Errors have a 4xx or 5xx status and a JSON body saying what went wrong.
- Times are milliseconds since the epoch; durations are seconds unless the name says otherwise.
- Every write (`POST`, `PUT`, `PATCH`, `DELETE`) is in the org's audit log.

## Endpoints

| Endpoint | Scope | What |
| --- | --- | --- |
| `POST /query` | read | Query logs or metrics; see [Explore and the query API](/docs/explore-and-query-api/) |
| `GET /names?kind=metric\|service&prefix=` | read | Metric names or services seen in the last 7 days |
| `GET /checks`, `GET /checks/:id` | read | Checks with status, ping URL and the last 10 pings |
| `POST /checks`, `PATCH /checks/:id`, `DELETE /checks/:id` | write | Create, change, pause (`{"paused": true}`) and delete; see [Checks](/docs/checks/) |
| `GET /monitors` | read | Monitors with status and last value |
| `POST /monitors`, `PATCH /monitors/:id`, `DELETE /monitors/:id` | write | See [Monitors](/docs/monitors/) |
| `GET /events?before=` | read | Recent alert events |
| `GET /archive` | read | Each archived, held or dropped day |
| `POST /archive/retry` | admin | Retry the archive now |
| `GET /ingest-keys`, `POST /ingest-keys`, `DELETE /ingest-keys/:id` | admin | Ingest keys; `POST` returns the key once |
| `GET /settings`, `PUT /settings` | admin | `{"alert_endpoint", "grace_days"}`; `PUT` also takes `"routing_key"` (write-only, `""` clears it) |
| `POST /settings/test-alert` | admin | Send a test alert |

The Shift routing key can be set in the app's **Alerts** page or with an API key that has the `admin` scope; `GET /settings` only says whether it is set (`routing_key_set`).

Members, invites, API keys, storage, usage and the audit log are platform endpoints under `/api/orgs/:org/...`, managed in Settings.