XBASE API: overview
What the XBASE API does, the base URL, how to authenticate and the list of endpoints for WhatsApp, Instagram, webhooks and external agents.
Updated on
The XBASE API lets another system use your workspace: send WhatsApp templates and messages, reply to Instagram comments and DMs, receive events by webhook and review the replies of an external agent.
Each call uses a workspace API key, with only the permissions you choose.
Base URL
All routes are under:
https://api.xbase.app/api/external/v1Request and response bodies are JSON (Content-Type: application/json). Dates come in ISO 8601, in UTC.
Authentication
Send the key in the Authorization header of every request:
Authorization: Bearer xsk_...The key starts with xsk_, works only in the workspace where it was created and only for the scopes checked on it. See how to create one in Authentication.
Endpoints
| Method and route | Scope | What it does |
|---|---|---|
GET /me | any | Workspace and scopes of the key |
GET /whatsapp/numbers | whatsapp:send | Workspace WhatsApp numbers |
GET /whatsapp/templates | whatsapp:send | Templates of each number |
POST /whatsapp/templates | whatsapp:send | Sends an approved template, at any time |
POST /whatsapp/messages | whatsapp:send | Sends a message (text, media, location, buttons, list or Flow) within the 24-hour window |
POST /whatsapp/messages/{messageId}/reaction | whatsapp:send | Reacts to a message |
POST /whatsapp/messages/{messageId}/read | whatsapp:send | Marks a received message as read |
GET /whatsapp/flows | whatsapp:send | Published Flows of a number |
GET /instagram/accounts | instagram:read | Connected Instagram accounts |
POST /instagram/comments/{commentId}/reply | instagram:act | Replies to a comment in public |
POST /instagram/comments/{commentId}/private-reply | instagram:act | Replies to the comment's author by DM |
POST /instagram/comments/{commentId}/hide | instagram:act | Hides or shows a comment |
POST /instagram/messages | instagram:act | Sends a DM |
GET /webhook · PUT /webhook · DELETE /webhook | webhooks:manage | Gets, sets up or turns off the key's webhook |
POST /agents/{agentId}/output-review | guardrails:review | Reviews the reply of an external agent |
Scopes
When you create the key, you check the permissions. Each one is a scope:
| Scope | On screen | Allows |
|---|---|---|
whatsapp:send | Send WhatsApp messages | listing numbers, templates and Flows, sending templates and messages, reacting and marking as read |
instagram:read | Read Instagram accounts | listing the connected accounts |
instagram:act | Reply, hide and send DMs on Instagram | replying to and hiding comments and sending DMs |
webhooks:manage | Receive events (comments and DMs) by webhook | setting up and turning off the webhook |
guardrails:review | Review agent replies (guardrails) | reviewing the reply of an external agent |
A route called without the scope returns 403 MISSING_SCOPE.
Rules and limits
- Everything is bound to the key's workspace. A number, account, agent or conversation from another workspace returns 404, as if it did not exist.
- The key is not a person. It does not sign in to XBASE on screen and does not use the permissions of whoever created it: only what the scopes allow counts.
- Meta's limits still apply. For example, an Instagram DM and a WhatsApp free-form message only go out within the 24-hour window, and a WhatsApp template must be approved.
- Errors have a stable
code, which your integration should handle instead of the message text: Errors.