Base URL
All request/response examples in this documentation use
https://api.xobito.com — swap in your own environment’s host if you’re pointed at a different one.Authentication
Every request carries your API key in a header — there’s no OAuth flow, no bearer token exchange:Making a request
GET routes take query/path parameters only. Every list/write route in this API takes a JSON body on POST/PUT, even list — there’s no GET with query-string filters:
cURL
Response format
Every response — success or error — shares one envelope:200
422 error
An internal code, e.g.
"HC-1" for a generic success, "HC-10" for a generic 422. Not consistent across routes for the same conceptual error — a “not found” is C-1/data_not_found on some routes and CT-1/validation.not_found or ORG-20/a resource-specific *_not_found on others, documented per-route throughout this API. Don’t match on code alone across different endpoints; see API Error Codes and Responses.Machine-readable outcome name, e.g.
"success_200", "error_422", or a route-specific "validation.xxx_not_found".The actual payload on success — shape documented per-endpoint throughout this API. Absent on error responses.
Status codes observed across this API
payment_required — the organization has no active subscription. Documented on most write/list routes; not independently reproduced live on every single one.A missing, invalid, revoked, or expired
x-api-key. See Authentication.Sending messages is asynchronous
The three send calls (template, service message and canned response) don’t wait for the message to be sent. They check the channel (and the template or canned response), queue the message, and returnmessage_id with status: "queued" straight away. A 200 means “accepted”, not “sent”. Track what happens next with message webhooks. See Sending is asynchronous for the details, including the cases where a queued message is dropped without an error.
Scopes
Every route requires a scope in theresource:read/resource:write shape (e.g. contact:read, chat:write) — inferred by convention from the resource each route operates on, and noted on every endpoint page, but not independently confirmed against a key with mismatched scopes for every single route. See API Permissions and Scopes for the full list.
Next steps
API Authentication with API Keys
Create, rotate, and scope an API key.
API Permissions and Scopes
Every scope this API checks, and what it gates.
API Error Codes and Responses
The full error envelope and code reference.
List and Search Channels
A good first real call — no write scope needed.