#Overview
The CX-Engine API is a REST API that returns JSON responses. It is split into two distinct layers that reflect the platform's multi-tenant architecture:
- Central API — account-level operations (registration, login, workspace management, invitations)
- Workspace API — tenant-level operations (customers, contacts, users, integration keys, etc.)
#Available resources
| Page | Endpoints |
|---|---|
| Authentication | OAuth 2.0, login, logout, token switching |
| Customers | Customer accounts, account resolution, regional settings |
| CRM Lookup | Contact search and creation, call and chat logging in the connected CRM |
| Call History | Calls received by CX-Engine |
| Users, Roles & Invitations | Users, roles, organisations, invitations |
| Contacts | Contacts of the customer accounts |
| Integration Keys | CRM integration keys of a customer |
| Smart Routings | Inbound rules, groups, time spans, exceptions, lookups, CFD tokens |
| Smart Routings — CTIs, Contacts, Geo Routing, Surveys | Other Smart Routings resources |
#Customer-scoped endpoints
Many workspace endpoints act on a single customer account (CRM lookups, call history, integration keys, Smart Routings). The customer is not deduced from the token: pass it with the customer_account query parameter. See Selecting the customer account.
#Base URLs
| Layer | Base URL |
|---|---|
| Central API | https://{central-domain}/api |
| Workspace API | https://{workspace-subdomain}.{central-domain}/api |
The workspace subdomain is assigned when a workspace is created (e.g. mycompany.cx-engine.app).
#Authentication
All authenticated endpoints require a Bearer token sent in the Authorization header:
Authorization: Bearer {token}
Tokens are obtained via the /api/login endpoint (see Authentication). Tokens are issued per scope: a central token works only against the central API; a workspace token works only against that workspace's API.
To switch between a central token and a workspace token, use the POST /api/switch-to endpoint.
#Request Format
Authenticated write endpoints (POST, PUT) expect a JSON body:
Content-Type: application/json
#Response Format
All responses are JSON objects. Successful responses generally include the requested data directly. Error responses follow this shape:
{
"message": "Human-readable error description.",
"error": "machine_readable_code"
}
Validation errors include a hint array with field-level messages:
{
"response": "bad request: please check body parameters.",
"hint": ["The name field is required."]
}
#HTTP Status Codes
| Code | Meaning |
|---|---|
200 |
OK — request succeeded |
201 |
Created — resource was created or updated |
400 |
Bad Request — malformed request or validation failure |
401 |
Unauthorized — missing or invalid token |
403 |
Forbidden — authenticated but not permitted |
404 |
Not Found — resource does not exist |
422 |
Unprocessable — semantic validation error |
500 |
Internal Server Error |
#Pagination
List endpoints that support pagination return a standard paginated response:
{
"data": [...],
"current_page": 1,
"last_page": 4,
"per_page": 20,
"total": 72
}
Pass ?per_page=N to control page size and ?page=N to navigate pages.