HTTP API
Base URL: https://api.holemonitor.live. The full reference is the OpenAPI 3.1 document at /v1/openapi.json.
Authentication
- API keys:
Authorization: Bearer hm_.... Create and revoke keys in the dashboard. A key is shown once and has a scope ofreadorwrite. - 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_cursorisnullon the last page. - Errors are RFC 9457 problem documents with
content-type: application/problem+json. See Errors. POSTroutes accept anIdempotency-Keyheader. A repeat with the same key within 24 hours returns the stored response withidempotent-replayed: trueand 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-policyand, when limited,ratelimitandretry-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.