Vatli REST API — overview and authentication

The Vatli API lets your own systems send WhatsApp messages, manage contacts, read conversations and launch broadcasts — the same things you do in the dashboard.

Base URL

https://app.vatli.co/api/v1

All requests and responses are JSON over HTTPS.

Authentication

Every request carries an API key as a bearer token:

Authorization: Bearer vatli_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keys are workspace-scoped: a key acts on the one workspace it was created in. Create keys in Settings → API keys — see Create and manage API keys.

Scopes

A key can do only what its scopes allow. Grant the minimum.

A key with no scopes can still call GET /api/v1/me — useful to check a key works.

Response envelope

// success
{ "data": { /* ... */ } }

// failure
{ "error": { "code": "forbidden", "message": "This API key is missing the 'messages:send' scope" } }

Branch on error.code — it’s stable. error.message is for humans and may change.

Rate limits

120 requests per minute per key. A 429 response includes:

• Retry-After — seconds until you can retry
• X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Pagination

List endpoints return up to limit items (default 50, max 100) and a cursor:

GET /api/v1/contacts?limit=50
→ { "data": [ … ], "meta": { "next_cursor": "eyJ…" } }

GET /api/v1/contacts?limit=50&cursor=eyJ…
→ { "data": [ … ], "meta": { "next_cursor": null } }   // last page

Pass the cursor back exactly as you got it. next_cursor: null means there are no more pages.

Check your key

curl https://app.vatli.co/api/v1/me \
  -H "Authorization: Bearer vatli_live_xxx"

{
  "data": {
    "account": { "id": "…", "name": "Acme Inc" },
    "key": { "id": "…", "scopes": ["messages:send"] }
  }
}

Endpoints