# LanaChat API: быстрое начало, аутентификация и ошибки

_API · Чтение 8 мин · Обновлено 2026-10-22 · https://lanachat.ai/guides/ru/api-overview/_

Всё, что ваша команда делает в Console, может делать и ваш код. LanaChat API читает и изменяет весь ваш рабочий пространство: авторов, аккаунты Telegram, AI Brains, скрипты, Vault, фанатов и разговоры, трекинг-ссылки, биллинг и вашу команду. Это простой JSON поверх HTTPS, один URL на ресурс, с теми же правами, что и Console. Вебхуки отправляют события на ваш сервер, а сервер MCP позволяет AI-ассистенту, например Claude или Cursor, работать в вашем пространстве с тем же токеном.

> Note: Это публичная документация API. Эндпоинты, помеченные как **Planned**,, это опубликованный контракт, на котором построен бэкенд: они пока не отвечают. [Подключение MCP](https://lanachat.ai/guides/ru/api-mcp/) использует те же токены доступа.

## Что вы можете создать

- Панель продаж в ваших собственных инструментах: выручка за сегодня по автору, по ссылке, по источнику.
- Оповещения в Slack или Telegram, когда фанат покупает, когда разговор требует проверки или когда аккаунт теряет соединение.
- Скрипт настройки, который добавляет автора, подключает его аккаунты, загружает Vault и пишет первый скрипт.
- Трекинг-пайплайн: создавайте по одной ссылке на каждую рекламу, считывайте клики, разговоры и покупателей каждый час.
- AI-ассистент, который набрасывает скрипты и изменения персонажа для вашего просмотра через [MCP](https://lanachat.ai/guides/ru/api-mcp/).

## Быстрый старт за 5 минут

1. В Console откройте **Users › API & MCP** и нажмите **Create token**.
2. Назовите его (например, "Reporting script"), выберите **Custom permissions** и отметьте необходимые права, например **Read fans and conversations** и **Read sales**.
3. Сохраните, затем нажмите **Copy token**. Токен показывается один раз.

**4. Храните его в переменной окружения**, чтобы он не лежал в коде:

```bash
export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"
```

**5. Сделайте первый запрос.** Он вернёт ваше рабочее пространство и права токена:

```bash
curl https://api.lanachat.ai/v1/workspace \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```js
const res = await fetch('https://api.lanachat.ai/v1/workspace', {
  headers: { Authorization: `Bearer ${process.env.LANACHAT_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const workspace = await res.json();
console.log(workspace.name, workspace.token.permissions);
```

```python
import os
import requests

r = requests.get(
    "https://api.lanachat.ai/v1/workspace",
    headers={"Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["name"])
```

```json
{
  "id": "ws_7Hq2",
  "name": "Mia Agency",
  "kind": "agency",
  "timezone": "Europe/Paris",
  "token": { "id": "tok_31", "name": "Reporting script", "permissions": ["can_fan_read", "can_sales_read"], "expires_at": "2027-01-06T00:00:00Z" }
}
```

Вот и всё: остальные эндпоинты работают так же. Готовые скрипты, в [API quick recipes](https://lanachat.ai/guides/ru/api-recipes/).

## Все ресурсы

| Resource | Что охватывает | Руководство |
|---|---|---|
| Workspace | `GET /workspace`: рабочее пространство и права токена | Эта страница |
| Creators | Авторы, идентификация, персона и прогресс настройки | [Creators](https://lanachat.ai/guides/ru/api-creators/) |
| Telegram accounts | Аккаунты, пулы, настройки пулов и истории | [Telegram accounts](https://lanachat.ai/guides/ru/api-telegram-accounts/) |
| AI Brains | Brains, черновики, публикация, версии и Playground | [AI Brains](https://lanachat.ai/guides/ru/api-ai-brains/) |
| Scripts | Скрипты, шаги и папки | [Scripts](https://lanachat.ai/guides/ru/api-scripts/) |
| Vault | Медиа, папки и подписанные загрузки | [Vault](https://lanachat.ai/guides/ru/api-vault/) |
| Fans and conversations | Фанаты, списки, продажи фаната, сообщения, takeover | [Conversations](https://lanachat.ai/guides/ru/api-conversations/) |
| Tracking | Ссылки, домены, пиксели, события и статистика | [Tracking](https://lanachat.ai/guides/ru/api-tracking/) |
| Billing | Баланс, журнал, депозиты, лицензии, выводы, счета | [Billing](https://lanachat.ai/guides/ru/api-billing/) |
| Team | Участники, роли и токены доступа | [Team](https://lanachat.ai/guides/ru/api-team/) |
| Webhooks | События, отправляемые на ваш сервер, подписи и повторные попытки | [Webhooks](https://lanachat.ai/guides/ru/api-webhooks/) |
| MCP | Сервер для AI-ассистентов и его инструменты | [MCP](https://lanachat.ai/guides/ru/api-mcp/) |

## Базовый URL и версии

Все пути в этих руководствах относительны к:

```text
https://api.lanachat.ai/v1
```

Версия указана в пути. При серьёзных изменениях появляется новая версия (`/v2`); новые поля и эндпоинты добавляются в `/v1` без уведомлений, поэтому игнорируйте незнакомые поля.

## Аутентификация

Каждый запрос несёт ваш токен в заголовке `Authorization` после слова `Bearer`:

```text
Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f
```

- Создавайте, редактируйте, обновляйте и отзывайте токены в **Users › API & MCP** или через [эндпоинты токенов](https://lanachat.ai/guides/ru/api-team/). Страницу могут открыть только владелец рабочего пространства и владельцы агентств.
- Токен показывается один раз при создании. Храните его как пароль; **Rotate** или **Revoke** можно на той же странице.
- Запрос без валидного токена возвращает `401`. Токен без нужного права, `403`.
- Токены никогда не передавайте в URL или в браузерном коде: вызывайте API с сервера.
- Используйте отдельный токен для каждого скрипта или ассистента, чтобы можно было менять или отзывать их по отдельности.

## Рабочие пространства

Токен принадлежит одному рабочему пространству, в котором он создан. Каждый запрос читает и пишет только в это пространство; в путях нет id рабочего пространства. Токен владельца (рабочее пространство, управляющее несколькими агентствами) может действовать от имени одного из агентств с заголовком `LanaChat-Workspace: ws_…`; любой другой токен с этим заголовком получит `403`.

## Права доступа

Каждый эндпоинт указывает, какое право ему нужно. Это те, что вы отмечаете при создании токена:

| Permission | В Console | Даёт |
|---|---|---|
| `can_setup` | Управление настройкой рабочего пространства | Авторов, медиа, аккаунты Telegram, скрипты и участников команды |
| `can_engine` | Доступ к настройкам AI | Черновики AI Brain, AI-настройки скриптов и тесты |
| `can_publish` | Публикация черновиков AI Brain | Публикация черновика brain (требует `can_engine`) |
| `can_ai_test` | Тестирование Advanced AI черновиков | Тестирование черновиков с Advanced AI (только для владельца рабочего пространства) |
| `can_ai_tune` | Настройка Advanced AI | Изменение чувствительности Advanced AI (только для владельца рабочего пространства) |
| `can_ai_publish` | Публикация профилей Advanced AI | Публикация профилей с Advanced AI (только для владельца рабочего пространства) |
| `can_commercial_reports` | Чтение отчётов коммерческих экспериментов | Эксперименты и их отчёты (только для владельца рабочего пространства) |
| `can_fan_read` | Чтение фанатов и разговоров | Фанаты, разговоры и сообщения, только для чтения |
| `can_fan_import` | Импорт истории фанатов | Импорт прошлых фанатов и сообщений |
| `can_sales_read` | Чтение продаж | Продажи, статистика и цифры на дашборде |
| `can_chat` | Новое: чат с фанатами | Отправка сообщений, реакций и takeover разговора |
| `can_tracking` | Новое: управление трекингом | Ссылки, домены, пулы, пиксели и события |
| `owner` | Токен владельца | Биллинг, роли, вебхуки и токены доступа; создаётся только владельцем рабочего пространства |

- Отключение **Access AI configuration** (`can_engine`) также отключает публикацию, Advanced AI и отчёты экспериментов.
- `can_chat`, `can_tracking` и токен `owner`, в планах, Console пока их не предлагает.

## Запросы и ответы

- Тела, JSON (`Content-Type: application/json`), в UTF-8. Загрузки проходят через [подписанный URL](https://lanachat.ai/guides/ru/api-vault/), не через API.
- Id, строки с префиксом, указывающим тип: `cr_` автор, `acc_` аккаунт Telegram, `pool_`, `sto_` история, `br_` brain, `scr_` скрипт, `med_` медиа, `fan_`, `conv_` разговор, `msg_`, `lnk_` ссылка, `px_` пиксель, `mem_` участник, `tok_` токен.
- Время, ISO 8601 в UTC (`2026-10-06T14:05:00Z`). Дни в статистике, по UTC.
- Деньги, в центах США (`amount_cents: 1900` это $19.00). Telegram Stars, целые числа (`stars: 250`).
- `PATCH` меняет только поля, которые вы отправляете. `PUT` заменяет весь объект.
- `POST`, создающий объект, отвечает `201` с новым объектом; другие успешные вызовы, `200`.

## Пагинация

Каждый список возвращает одну страницу и курсор к следующей:

```bash
curl "https://api.lanachat.ai/v1/fans?limit=50&cursor=eyJpZCI6ImZhbl85MjAifQ" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [ { "id": "fan_921", "display_name": "Marco", "creator_id": "cr_lea" } ],
  "next_cursor": "eyJpZCI6ImZhbl85NzAifQ"
}
```

- `limit` от 1 до 100, по умолчанию 25.
- `next_cursor` равен `null` на последней странице. Курсор непрозрачен: передавайте его как есть, не создавайте сами.
- Списки отсортированы от новых к старым, если не указано иное.

Чтобы прочитать все страницы, делайте цикл, пока `next_cursor` не станет `null`:

```js
async function all(path) {
  const items = [];
  let cursor = null;
  do {
    const url = new URL('https://api.lanachat.ai/v1' + path);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.LANACHAT_TOKEN}` } });
    if (!res.ok) throw new Error((await res.json()).error.message);
    const page = await res.json();
    items.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);
  return items;
}

const fans = await all('/fans?creator_id=cr_lea');
```

```python
import os
import requests

def all_items(path, **params):
    items, cursor = [], None
    while True:
        r = requests.get(
            "https://api.lanachat.ai/v1" + path,
            params={**params, "limit": 100, **({"cursor": cursor} if cursor else {})},
            headers={"Authorization": f"Bearer {os.environ['LANACHAT_TOKEN']}"},
            timeout=30,
        )
        r.raise_for_status()
        page = r.json()
        items += page["data"]
        cursor = page["next_cursor"]
        if not cursor:
            return items

fans = all_items("/fans", creator_id="cr_lea")
```

## Ошибки

Ошибка возвращает статус 4xx или 5xx и всегда такой же формат тела:

```json
{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is $12.40 and this pack costs $170.00. Top up first."
  }
}
```

| Статус | `code` | Когда |
|---|---|---|
| 400 | `invalid_request` | Отсутствует поле или неверный формат; `message` объясняет, что именно |
| 401 | `unauthorized` | Нет токена, или токен отозван/истёк |
| 402 | `insufficient_balance` | Баланс не покрывает покупку |
| 403 | `forbidden` | Токен не имеет нужного права |
| 404 | `not_found` | Id не существует в этом рабочем пространстве |
| 409 | `conflict` | Изменение нарушит правило (дубликат slug, последний аккаунт отправки автора) |
| 429 | `rate_limited` | Слишком много запросов; ждите `Retry-After` секунд |
| 500 | `server_error` | Ошибка на нашей стороне; повторите позже с тем же `Idempotency-Key` |

`message`, простое предложение на английском, которое можно показать человеку. В коде ориентируйтесь на `code`, а не на `message`.

## Лимиты запросов

Каждый токен может отправлять **600 запросов в минуту**. В ответах есть заголовки `RateLimit-Limit`, `RateLimit-Remaining` и `RateLimit-Reset` (секунды до сброса окна). При превышении лимита API отвечает `429` с заголовком `Retry-After`. Отправка сообщений фанату также ограничена лимитами Telegram: смотрите [правила пулов](https://lanachat.ai/guides/ru/api-telegram-accounts/).

Небольшой помощник, который ждёт и повторяет запросы при `429` и ошибках `5xx`:

```js
async function lanachat(method, path, body) {
  const key = crypto.randomUUID();   // one key per action: a retry never does the work twice
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch('https://api.lanachat.ai/v1' + path, {
      method,
      headers: {
        Authorization: `Bearer ${process.env.LANACHAT_TOKEN}`,
        'Content-Type': 'application/json',
        ...(method === 'POST' ? { 'Idempotency-Key': key } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt;
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const data = await res.json();
    if (!res.ok) throw Object.assign(new Error(data.error.message), { code: data.error.code, status: res.status });
    return data;
  }
  throw new Error('LanaChat API: too many retries');
}
```

Используйте везде: `await lanachat('GET', '/creators')`, `await lanachat('POST', '/links', { … })`.

## Идемпотентность

Отправляйте заголовок `Idempotency-Key` (любая уникальная строка до 255 символов, UUID подходит) в каждом `POST`. Если тот же ключ приходит в течение 24 часов, API возвращает первый результат повторно, не выполняя действие дважды: сетевая ошибка не приведёт к повторной отправке сообщения или покупке пакета.

```bash
curl -X POST https://api.lanachat.ai/v1/billing/licences/buy \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: 4b7f2a8e-1c3d-4e5f-9a0b-6c7d8e9f0a1b" \
  -H "Content-Type: application/json" \
  -d '{"pack": 10, "qty": 1}'
```

Тот же ключ с другим телом возвращает `409`. В shell `$(uuidgen)` создаёт новый ключ для каждого действия.

## Вебхуки

Вместо опроса API каждую минуту, позвольте LanaChat звонить вам. Вебхук отправляет HTTPS `POST` на ваш сервер, когда фанат пишет впервые, покупает, получает возврат, когда медиа готово или аккаунт теряет соединение. Каждая доставка подписана (HMAC-SHA256) и повторяется в течение 24 часов. События, полезные нагрузки и проверка подписи на Node и Python описаны в [Webhooks](https://lanachat.ai/guides/ru/api-webhooks/).

## MCP для AI-ассистентов

MCP, открытый стандарт, позволяющий AI-ассистенту использовать инструменты в приложении. Сервер MCP LanaChat позволяет Claude, Cursor или любому MCP-клиенту читать ваших авторов, набрасывать скрипты, редактировать черновик brain и читать ваши продажи с тем же токеном доступа и правами. В Claude Code одна команда подключает его:

```bash
claude mcp add --transport http lanachat https://app.lanachat.ai/mcp \
  --header "Authorization: Bearer $LANACHAT_TOKEN"
```

Настройки для каждого ассистента и список инструментов находятся в [API & MCP](https://lanachat.ai/guides/ru/api-mcp/).

## Похожие статьи

- [API быстрые рецепты: копируйте, вставляйте, запускайте](https://lanachat.ai/guides/ru/api-recipes/)
- [API и MCP: подключение AI-ассистента](https://lanachat.ai/guides/ru/api-mcp/)
- [API: вебхуки, события и подписи](https://lanachat.ai/guides/ru/api-webhooks/)