---
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.)

## 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.