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 або через token endpoints. Сторінку можуть відкрити лише власник робочого простору та власники агенцій.
• Токен показується лише один раз при створенні. Зберігайте його як пароль; 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. Завантаження проходять через signed 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: див. pool rules.

Невеликий помічник, що чекає і повторює при 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 годин. Події, payload-и і перевірка підпису в 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.