# HTTP API

Base URL: `https://api.holemonitor.live`. The full reference is the OpenAPI 3.1 document at [/v1/openapi.json](/v1/openapi.json).

## Authentication

- API keys: `Authorization: Bearer hm_...`. Create and revoke keys in the [dashboard](/dashboard/). A key is shown once and has a scope of `read` or `write`.
- Dashboard session: a cookie set by magic-link sign-in.

A key can manage endpoints, filters and deliveries and read advisories. Keys, billing and the account itself are managed only from a dashboard session. Another account's object returns 404.

## Routes

| Method and path | Purpose | Auth |
| --- | --- | --- |
| `GET /v1/account` | Plan, limits and today's usage | Session or key |
| `DELETE /v1/account` | Delete the account | Session |
| `GET`, `POST /v1/keys`, `DELETE /v1/keys/{id}` | List, create, revoke API keys | Session |
| `GET`, `POST /v1/endpoints` | List and create endpoints | Session or key |
| `GET`, `PATCH`, `DELETE /v1/endpoints/{id}` | Read, change, pause, delete | Session or key |
| `POST /v1/endpoints/{id}/verify` | Resend verification, or submit the code | Session or key |
| `POST /v1/endpoints/{id}/rotate-secret` | New secret; the old one stays valid 24 h | Session or key |
| `POST /v1/endpoints/{id}/test` | Send a test event | Session or key |
| `GET`, `POST`, `PUT /v1/endpoints/{id}/filters` | List, create, replace all filters | Session or key |
| `PATCH`, `DELETE /v1/filters/{id}` | Change or delete a filter | Session or key |
| `POST /v1/filters/preview` | Retained events the conditions would have matched | Session or key |
| `GET /v1/deliveries` | Delivery log; `include=body` returns bodies | Session or key |
| `POST /v1/deliveries/{id}/redeliver` | Queue a delivery again | Session or key |
| `GET /v1/advisories/{id}` | Current merged record by any alias; `content=full` for prose | Session or key |
| `GET /status` | Last successful run of each source | None |

Write routes need a `write` key.

## Conventions

- JSON in and out.
- Lists use cursor pagination: `?limit=` (1 to 200, default 50) and `?cursor=`. The response is `{ "data": [...], "next_cursor": "..." }`; `next_cursor` is `null` on the last page.
- Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem documents with `content-type: application/problem+json`. See [Errors](/docs/errors/).
- `POST` routes accept an `Idempotency-Key` header. A repeat with the same key within 24 hours returns the stored response with `idempotent-replayed: true` and creates nothing. Reusing a key for a different route returns 409.
- Rate limits: 120 requests a minute per key, 300 per IP without a key. Responses carry `ratelimit-policy` and, when limited, `ratelimit` and `retry-after`. A limited request returns 429.
- Timestamps are ISO 8601 UTC.
- A changed endpoint URL returns the endpoint to `unverified`.

## Plan limits

Creating or changing an endpoint, filter or key past the plan's limit returns 403 with `limit` naming the limit. See [Plans](/docs/plans/).
