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

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

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

• Панель продаж в ваших собственных инструментах: выручка за сегодня по автору, по ссылке, по источнику.
• Оповещения в Slack или Telegram, когда фанат покупает, когда разговор требует проверки или когда аккаунт теряет соединение.
• Скрипт настройки, который добавляет автора, подключает его аккаунты, загружает Vault и пишет первый скрипт.
• Трекинг-пайплайн: создавайте по одной ссылке на каждую рекламу, считывайте клики, разговоры и покупателей каждый час.
• AI-ассистент, который набрасывает скрипты и изменения персонажа для вашего просмотра через MCP.

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

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

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

export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"

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

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

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

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"])

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

Все ресурсы #

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

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

https://api.lanachat.ai/v1

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

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

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

Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f

• Создавайте, редактируйте, обновляйте и отзывайте токены в Users › API & MCP или через эндпоинты токенов. Страницу могут открыть только владелец рабочего пространства и владельцы агентств.
• Токен показывается один раз при создании. Храните его как пароль; Rotate или Revoke можно на той же странице.
• Запрос без валидного токена возвращает 401. Токен без нужного права, 403.
• Токены никогда не передавайте в URL или в браузерном коде: вызывайте API с сервера.
• Используйте отдельный токен для каждого скрипта или ассистента, чтобы можно было менять или отзывать их по отдельности.

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

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

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

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

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

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

• Тела, JSON (Content-Type: application/json), в UTF-8. Загрузки проходят через подписанный URL, не через 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.

Пагинация #

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

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

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

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

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

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');

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 и всегда такой же формат тела:

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

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

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

Каждый токен может отправлять 600 запросов в минуту. В ответах есть заголовки RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset (секунды до сброса окна). При превышении лимита API отвечает 429 с заголовком Retry-After. Отправка сообщений фанату также ограничена лимитами Telegram: смотрите правила пулов.

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

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 возвращает первый результат повторно, не выполняя действие дважды: сетевая ошибка не приведёт к повторной отправке сообщения или покупке пакета.

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.

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

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

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

Настройки для каждого ассистента и список инструментов находятся в API & MCP.