API keys & requests

Base URL and versioning

All calls go to https://api.yasend.dev/v1/....

Within /v1: changes are only additive: new endpoints, new optional fields, new event types and new error codes. Your code should ignore fields it doesn't know.
Breaking changes: these would ship as /v2.

Send your key as a bearer token:

Authorization: Bearer ysk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

There are two kinds of key:

Key	Created	Can do
Tenant key	Portal → API keys, or `POST /v1/api-keys`	Everything in your account: every session, webhooks, keys, usage
Session key	Returned once by `POST /v1/sessions` (or `POST /v1/api-keys` with a `sessionId`)	Only that one session. Ideal for a single app or server that sends from one number

With a session key, you can leave sessionId out of sends. If your account has exactly one session, you can leave it out with a tenant key too.

Rotate a session's key with POST /v1/sessions/{id}/regenerate-key.
Revoke any key with DELETE /v1/api-keys/{id}.
Storage: keys are stored hashed, so we can't show a key again. If you lose one, create a new one.

Keep keys on your server. Never ship them in a mobile app or a web page: anyone who has the key can send messages from your number.

Bodies: requests and responses are JSON (Content-Type: application/json). Field names are camelCase.
Times: ISO 8601, in UTC.
Request IDs: every response carries an X-Request-Id header. It also appears as requestId inside every error. If you send your own X-Request-Id (8–64 characters: letters, digits, ., _, : or -), YASend keeps it, so you can trace a call end to end. Include it when you contact support.
Errors: they always have the same shape. See Errors.
Retrying sends: use an Idempotency-Key header so a send is never duplicated. See Sending messages.

The original self-hosted API also works:

Existing integrations can switch to YASend Cloud by changing only the base URL and the key. New integrations should use /v1.