# LanaChat API: швидкий старт, автентифікація та помилки

_API · Читання 8 хв · Оновлено 2026-10-22 · https://lanachat.ai/guides/uk/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/uk/api-mcp/) використовує ті ж токени доступу.

## Що ви можете створити

- Панель продажів у ваших власних інструментах: сьогоднішній дохід по авторці, по посиланню, по джерелу.
- Сповіщення в Slack або Telegram, коли фан купує, коли розмова потребує перевірки або коли акаунт втрачає з’єднання.
- Скрипт налаштування, що додає авторку, підключає її акаунти, завантажує її Vault і пише перший скрипт.
- Трекінговий конвеєр: створюйте по одному посиланню на рекламу, читайте кліки, розмови та покупців щогодини.
- AI-асистент, який готує чернетки скриптів і зміни персонажа для вашого перегляду через [MCP](https://lanachat.ai/guides/uk/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/uk/api-recipes/).

## Кожен ресурс

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

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

Кожен шлях у цих посібниках відносний до:

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

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

## Автентифікація

Кожен запит несе ваш токен у заголовку `Authorization` після слова `Bearer`:

```text
Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f
```

- Створюйте, редагуйте, оновлюйте і відкликайте токени у **Users › API & MCP** або через [token endpoints](https://lanachat.ai/guides/uk/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. Завантаження проходять через [signed URL](https://lanachat.ai/guides/uk/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: див. [pool rules](https://lanachat.ai/guides/uk/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 годин. Події, payload-и і перевірка підпису в Node і Python описані в [Webhooks](https://lanachat.ai/guides/uk/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/uk/api-mcp/).

## Пов’язані статті

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