> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Обзор API

> Как обращаться к API Yume: базовые адреса, авторизация по JWT, выбор компании, пагинация и разделы справочника.

Справочник собран из самого бэкенда: каждый раздел слева — это отдельная OpenAPI-спецификация,
выгруженная из кода, поэтому список эндпоинтов и схемы полей всегда совпадают с тем, что отвечает сервер.

## Базовые адреса

<CodeGroup>
  ```bash Production theme={null}
  https://api.yume.cloud
  ```

  ```bash Stage theme={null}
  https://api.stage.yume.cloud
  ```
</CodeGroup>

Все пути в справочнике указаны от корня — например, `POST /v1/auth/login/` на проде это
`https://api.yume.cloud/v1/auth/login/`. Завершающий слэш обязателен.

## Авторизация

API использует JWT. Получите пару токенов по логину и паролю:

```bash theme={null}
curl -X POST https://api.yume.cloud/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"username": "user@example.com", "password": "..."}'
```

В ответе приходят `access` и `refresh`. `access` передаётся в заголовке `Authorization` каждого последующего запроса — вместе с
`X-Tenant-Id`, который выбирает компанию (см. ниже).

Когда `access` истекает, обменяйте `refresh` на новую пару через `POST /v1/auth/refresh/`.

<Note>
  `refresh`-токены ротируются: каждый обмен выдаёт новый `refresh`, а предыдущий перестаёт работать.
  Сохраняйте тот, что пришёл последним.
</Note>

## Выбор компании

Один пользователь может работать в нескольких компаниях, поэтому запрос должен говорить, о какой
идёт речь. Компанию задаёт заголовок `X-Tenant-Id` — в нём id компании из `GET /v1/tenant/`:

```bash theme={null}
curl https://api.yume.cloud/v1/crm/clients/ \
  -H "Authorization: Bearer <access>" \
  -H "X-Tenant-Id: 123"
```

Заголовок объявлен у каждого эндпоинта в справочнике и необязателен: если его не передать, компания
определяется по домену запроса. Для интеграции, которая ходит на общий `api.yume.cloud`, передавать
его нужно всегда.

<Warning>
  Сервер проверяет, что пользователь действительно состоит в указанной компании. Чужой `X-Tenant-Id`
  не даёт доступа к её данным ни на чтение, ни на запись.
</Warning>

## Пагинация

Списочные эндпоинты отдают страницу, а не весь набор:

```json theme={null}
{
  "page": 1,
  "count": 137,
  "next": "https://api.yume.cloud/v1/crm/clients/?page=2",
  "previous": null,
  "results": []
}
```

Страница выбирается параметром `page`, размер — параметром `pageSize` (по умолчанию 10, максимум 10000).

## Как читать справочник

Разделы слева повторяют деление API на бэкенде, а внутри раздела эндпоинты сгруппированы по ресурсам.
На странице каждого эндпоинта есть параметры, схемы запроса и ответа и примеры кода; поля, помеченные
`readOnly`, приходят от сервера и не принимаются на запись, `writeOnly` — наоборот.