Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Authenticate a request to the Mesub API

Every request carries the project's API key in the Authorization header, as a bearer token:
curl "https://api.mesub.io/v1/project" \
  -H "Authorization: Bearer $MESUB_API_KEY"
A project has one key at a time, and the key is the project: every route answers about that project only, and no call names a project id. The key starts with SUB_. Get your API key says where to create it and how to rotate it.
The key goes in the header, never in the query string: a query string ends up in access logs and in browser history.
Keep the key on your server. It creates subscriptions and reads your subscribers, so it never goes in a browser, a mobile app or a repository.

When the key is refused

StatuscodeMeaning
401missing_api_keyNo Authorization: Bearer header was sent
401invalid_api_keyNot a key Mesub issued, or one rotated since
{
    "statusCode": 401,
    "message": "That API key is not valid.",
    "error": "Unauthorized",
    "code": "invalid_api_key",
    "retryable": false,
    "request_id": "req_4f8KzQ2nVb7XcR1mT9wLp3sD"
}

Rate limits

Limits are per API key, per route, per minute.
CallsLimit
Reads: /v1/access, /v1/plans, /v1/subscriptions, /v1/project, /v1/events1,000 a minute
Writes: create, transaction, submit, retry, cancel, resume, close, their confirms60 a minute
Requests with no key, or with a wrong one, are counted by IP address instead: 120 a minute.
Every answer says where you stand in three headers: X-RateLimit-Limit, the route's limit, X-RateLimit-Remaining, the calls left in the window, and X-RateLimit-Reset, the seconds until the window starts over.
Past a limit, Mesub answers 429 rate_limited with a Retry-After header, in seconds. Pricing and limits has every other limit.