API overview

Base URLs

Production is https://api.heyservus.com (the SDK's default base URL); local dev is http://localhost:5080. All responses are JSON.

Four auth schemes, one per prefix

A request carries exactly the credential its route group expects, and the tenant is always derived from the credential, never from a request body:

• /auth/** — anonymous (register / login).
• /portal/** — a portal JWT (Authorization: Bearer <jwt>); tenant from the JWT's tenant claim.
• /v1/** — a per-tenant API key (X-Api-Key: <key> or Authorization: Bearer <key>).
• /internal/** — a shared internal token (the gateway only; not a public API).

API-key scopes

API keys carry scopes as a bitfield: Send=1, Read=2, Contacts=4, Admin=8. Grant the least a key needs; a key missing a route's scope gets 403. The raw key is shown once at creation — store it then; only a hash is kept.

Enums are numeric ordinals

The API serializes its enums as integers on the wire (e.g. channel: 1=WhatsApp, 2=Sms, 3=Email, 4=Telegram, 5=Push). The @servus/sdk client maps these to ergonomic string unions. The one exception: the channel in the message.inbound webhook is the channel name.

A caution: MessageStatus ordinals are not in lifecycle order (Sending is 5, Received is 6, appended after the original states). Compare to the named value — never compare ordinals to infer progress.

Errors are RFC 7807

Errors are application/problem+json: { type, title, status, detail, traceId }. A /v1 request with a missing/invalid key fails closed with 401 and a WWW-Authenticate: ApiKey header.