---
title: Introduction
excerpt: Overview of the CX-Engine REST API — architecture, base URLs, authentication and error handling.
order: 1
---

## 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](/en/docs/cx-api/authentication) | OAuth 2.0, login, logout, token switching |
| [Customers](/en/docs/cx-api/customers) | Customer accounts, account resolution, regional settings |
| [CRM Lookup](/en/docs/cx-api/lookup) | Contact search and creation, call and chat logging in the connected CRM |
| [Call History](/en/docs/cx-api/crm-calls) | Calls received by CX-Engine |
| [Users, Roles & Invitations](/en/docs/cx-api/users) | Users, roles, organisations, invitations |
| [Contacts](/en/docs/cx-api/contacts) | Contacts of the customer accounts |
| [Integration Keys](/en/docs/cx-api/integration-keys) | CRM integration keys of a customer |
| [Smart Routings](/en/docs/cx-api/smart-routings) | Inbound rules, groups, time spans, exceptions, lookups, CFD tokens |
| [Smart Routings — CTIs](/en/docs/cx-api/smart-routings-ctis), [Contacts](/en/docs/cx-api/smart-routings-contacts), [Geo Routing](/en/docs/cx-api/smart-routings-geo), [Surveys](/en/docs/cx-api/smart-routings-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](/en/docs/cx-api/smart-routings#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](/en/docs/cx-api/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:

```json
{
  "message": "Human-readable error description.",
  "error": "machine_readable_code"
}
```

Validation errors include a `hint` array with field-level messages:

```json
{
  "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:

```json
{
  "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.