API overview

Base URL is your gateway origin, for example https://gateway.example.com. Every endpoint lives under /api, takes and returns JSON (except media downloads), and returns errors as { error, code }.

Authentication

API	Header	Who holds it
Tenant	x-api-key: wa_...	The backend that uses one WhatsApp number
Admin	x-admin-key: <ADMIN_API_KEY> or the dashboard session cookie	Operators
Provisioning	x-provisioning-key: ...	A product that creates apps for its customers

API keys are stored hashed and shown once, at creation. POST /api/apps/:id/api-key issues a new one and the old key stops working at once.

Health

curl https://gateway.example.com/health

{ "ok": true, "time": "2026-10-01T02:00:00.000Z", "uptimeSec": 3600, "apps": { "total": 3, "ready": 2 } }

It checks the database and answers 503 { "ok": false } when it is down. Use it for uptime monitoring.

Conventions

• Bodies are JSON up to 25 MB.
• Timestamps in responses are ISO 8601 (createdAt, sentAt) except message timestamp, which is Unix seconds from WhatsApp.
• Unknown routes answer 404 { "code": "NOT_FOUND" }.