REST API

REST API reference

Pairing, send, history, MCP credentials and tenant flows. Interactive docs at /docs.

Public endpoints

Method	Path	Auth	Description
GET	`/health`	—	Liveness
GET	`/connect`	—	Pairing UI (QR / code + MCP copy)
POST	`/api/session/connect/kit`	Tenant	QR + code + image (best for agents)
POST	`/api/session/connect/code`	Tenant	8-digit pairing code
GET	`/api/session/connect/status`	Tenant / API key	Poll pairing; returns MCP on success
POST	`/api/send`	`wbot_...`	Send text or media
GET	`/api/history`	`wbot_...`	Message history with filters
GET	`/api/mcp/connection`	`wbot_...`	MCP config block
POST	`/mcp`	`mcp_...`	MCP Streamable HTTP transport

Connect kit flow

# Start
curl -X POST https://wamcp.up.railway.app/api/session/connect/kit \
  -H "X-Tenant-Key: tnt_..." \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"5511999999999"}'

# Poll (every 3s)
curl "https://wamcp.up.railway.app/api/session/connect/status?uuid=UUID" \
  -H "X-Tenant-Key: tnt_..."

# Optional QR image
curl "https://wamcp.up.railway.app/api/session/connect/kit-image?uuid=UUID" \
  -H "X-Tenant-Key: tnt_..." -o kit.png

Send message

curl -X POST https://wamcp.up.railway.app/api/send \
  -H "X-API-Key: wbot_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511888888888@s.whatsapp.net",
    "content": "Hello from REST API"
  }'

# With media
curl -X POST https://wamcp.up.railway.app/api/send \
  -H "X-API-Key: wbot_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511888888888@s.whatsapp.net",
    "content": "See attached",
    "media_url": "https://example.com/doc.pdf",
    "media_type": "document"
  }'

History query

curl "https://wamcp.up.railway.app/api/history?limit=25&chat_jid=5511999999999@s.whatsapp.net" \
  -H "X-API-Key: wbot_..."

White-label tenant provisioning

curl -X POST https://wamcp.up.railway.app/api/admin/tenants \
  -H "X-Admin-Token: $ADMIN_MASTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"acme","name":"Acme Corp WhatsApp"}'
# Response includes tenant_key (tnt_...) — shown once

HTTP status codes

401 — Missing or invalid tenant key, API key, or MCP token.
403 — Connect UUID belongs to another tenant.
408 — Pairing code not ready yet; keep polling.
409 — WhatsApp offline; reconnect or re-pair.