Pager API

Version 1.0.0. The machine-readable contract is at /v1/openapi.json.

The Pager API sends and receives SMS, manages the numbers that carry it, and records the consent that makes sending it lawful.

Authentication

Every endpoint except /v1/health requires an API key, presented as a bearer token:

Authorization: Bearer pk_live_...

A key belongs to exactly one account and every request is scoped to it. A resource belonging to another account is reported as 404, not 403: answering 403 would confirm the resource exists and let one tenant enumerate another's message and number ids by watching the status code.

The key is shown once, when it is issued, and stored only as a hash. A key that is lost cannot be recovered, only replaced.

Errors

Every failure has the same shape, so a client can write one error path:

{ "error": { "type": "invalid_request", "message": "...", "details": [ ... ] } }

Match on type, which is stable. message is for humans and may change without notice. details names the offending fields when the failure is attributable to input.

recipient_opted_out is its own type rather than a bare 403 because a caller has to be able to tell "this person unsubscribed, remove them from your list" apart from "your key may not do that". Retrying the first will never succeed.

Every response carries X-Correlation-Id. Quoting it in a support report identifies the exact request in the platform logs.

Pagination

Collections are cursor-paginated, not offset-paginated: an offset silently skips or repeats records when the underlying set changes between pages, which it does constantly here.

Read data, and if hasMore is true, pass nextCursor back as cursor. nextCursor is null on the last page, so a client can loop on its presence rather than comparing cursors.

Idempotency

POST /v1/messages accepts an Idempotency-Key header. A repeat of the same key returns the original message with 200 instead of sending a second one and returning 202. The distinction tells a caller retrying after a timeout that its first attempt did land.

Keys are at most 128 characters of letters, digits and ., :, _, -. An over-long key is rejected rather than truncated, because truncating would silently merge two distinct requests into one message.

Rate limits

Two buckets are charged: one for requests generally, and a narrower one for sends. A send costs carrier capacity shared with every other tenant, which is scarcer than the database query behind a GET; one bucket for both would let a client polling its message list starve its own sending.

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A client that reads them never has to be refused at all. A 429 also carries Retry-After.

A send refused by validation or replayed from an idempotency key is refunded, so a client retrying safely is not punished for it.

Webhooks

Events are delivered to the account webhook, or to a per-number override, as a POST with two headers:

Pager-Timestamp: 1735689600
Pager-Signature: v1=<hex hmac-sha256>

The signature covers ${timestamp}.${rawBody} under the account's own signing secret, which GET /v1/account returns. Verify over the raw body before parsing it, compare in constant time, and reject a timestamp outside a five-minute window — without that check a captured request can be replayed forever.

Each account has its own secret. Verification is symmetric, so a shared secret would let any customer mint signatures for any other customer's endpoint.

Failed deliveries are retried on a backoff of 1s, 5s, 30s and 120s — five attempts in total. 5xx, 429, 408 and network errors are retried; every other 4xx is final, since a 404 at a mistyped path will still be a 404. Redirects are never followed. Every attempt is recorded and readable at GET /v1/webhook_deliveries.

Endpoints