Pager API

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

Quick start

Send a message. Every one of these makes the same request against this deployment, reading your key from a PAGER_API_KEY environment variable. Create a key in the console.

curl -X POST https://lunarsoft.dev/v1/messages \
  -H "Authorization: Bearer $PAGER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+18288888202",
    "to":   "+12395550147",
    "body": "Your verification code is 481920."
  }'

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.

Destinations and pricing

Price book 2026-09-11 covers the mainland United States, Canada, and Bulgaria. Other international destinations and separately priced NANP territories remain unsupported.

- payg: United States and Canada: $0.0148; Bulgaria: $0.1500 per SMS segment (USD). - growth: United States and Canada: $0.0133; Bulgaria: $0.1485 per SMS segment (USD). - committed: United States and Canada: $0.0113; Bulgaria: $0.1465 per SMS segment (USD).

Rates apply to every encoded SMS segment, including concatenated and UCS-2 messages. The response records priceMicros and priceVersion; retries retain the original charge. Bulgaria includes a published $0.1390 provider portion plus the tier fee, not an additional US carrier surcharge.

Bulgaria requires an explicitly configured international route for your assigned sending number. Keep that E.164 number in from; the carrier uses its configured branded sender instead. Message records retain your assigned number for ownership and filtering. Branded international SMS is one-way: recipients cannot reply, and some carriers may rewrite the displayed sender. Provide a non-SMS opt-out/contact method rather than asking recipients to reply STOP. The hosted US 10DLC opt-in form is not an international signup form.

An unpriced destination or an unconfigured international sender is refused with 403 destination_not_supported before billing or queueing. Account ownership, sandbox verification, consent, balances and spending caps still apply.

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.

Versioning

/v1 is supported for the life of the product. It has no sunset date, and an integration written against it today keeps working. There are no Deprecation or Sunset headers, because there is nothing for them to announce.

Additive changes ship into /v1 without notice: new endpoints, new optional request fields, new response fields, new values in a field whose published schema says it may gain them, new error types for conditions that could not previously arise, and relaxed validation. message.status and the type in a failure body are the fields that carry that warning today. Parse responses permissively and treat an unrecognised enumerated value as one you do not handle rather than as an error; a client that rejects unknown fields, or that turns a published enumeration into a closed type, will break on a change this policy considers safe.

Nothing is ever removed, renamed, retyped or given a new meaning inside /v1, and no enumeration that does not advertise itself as open gains a value. An existing condition keeps its status and its error type — including against being subdivided into a finer one, which would stop the value a client matches on from arriving. A change that cannot be made additively arrives as /v2, served alongside /v1 rather than instead of it. Nobody is migrated.

The major component of info.version is the version this document describes and matches the prefix its paths are served under. It does not report the running build — GET /v1/health does that.

Endpoints