LanaChat API: szybki start, uwierzytelnianie i błędy

Wszystko, co Twój zespół robi w Console, może też zrobić Twój kod. LanaChat API odczytuje i zmienia całe Twoje środowisko pracy: twórczynie, konta Telegram, AI Brains, skrypty, Vault, fans i konwersacje, linki śledzące, rozliczenia oraz Twój zespół. To zwykłe JSON przez HTTPS, jeden URL na zasób, z tymi samymi uprawnieniami co Console. Webhooki wysyłają zdarzenia do Twojego serwera, a serwer MCP pozwala asystentowi AI, takiemu jak Claude czy Cursor, działać w Twoim środowisku z tym samym tokenem.

Co możesz zbudować #

• Panel sprzedaży w swoich narzędziach: dzisiejsze przychody na twórczynię, na link, na źródło.
• Alerty w Slack lub Telegram, gdy fan kupi, gdy konwersacja wymaga przeglądu lub gdy konto traci połączenie.
• Skrypt konfigurujący, który dodaje twórczynię, łączy jej konta, przesyła Vault i zapisuje pierwszy skrypt.
• Pipeline śledzenia: twórz jeden link na reklamę, co godzinę odczytuj kliknięcia, konwersacje i kupujących.
• Asystenta AI, który tworzy szkice skryptów i zmiany person, do Twojej weryfikacji, przez MCP.

Szybki start w 5 minut #

1. W Console otwórz Users › API & MCP i kliknij Create token.
2. Nadaj nazwę (np. „Reporting script”), wybierz Custom permissions i zaznacz potrzebne uprawnienia, np. Read fans and conversations oraz Read sales.
3. Zapisz, potem kliknij Copy token. Token jest pokazany tylko raz.

4. Przechowuj go w zmiennej środowiskowej, aby nigdy nie był w kodzie:

export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"

5. Wykonaj pierwsze wywołanie. Zwróci Twoje środowisko i uprawnienia tokena:

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" }
}

To wszystko: każdy inny endpoint działa tak samo. Gotowe skrypty znajdziesz w API quick recipes.

Wszystkie zasoby #

Bazowy URL i wersje #

Każda ścieżka w tych przewodnikach jest względem:

https://api.lanachat.ai/v1

Wersja jest w ścieżce. Zmiana łamiąca kompatybilność dostaje nową wersję (/v2); nowe pola i endpointy są dodawane do /v1 bez zapowiedzi, więc ignoruj nieznane pola.

Uwierzytelnianie #

Każde żądanie zawiera token w nagłówku Authorization, po słowie Bearer:

Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f

• Twórz, edytuj, rotuj i cofaj tokeny w Users › API & MCP lub przez endpointy tokenów. Tylko właściciel środowiska i właściciele agencji mogą otworzyć tę stronę.
• Token jest pokazany tylko raz, przy tworzeniu. Przechowuj go jak hasło; Rotate lub Revoke z tej samej strony.
• Żądanie bez ważnego tokena zwraca 401. Token bez wymaganego uprawnienia zwraca 403.
• Tokeny nigdy nie powinny być w URL ani w kodzie przeglądarki: wywołuj API z serwera.
• Używaj jednego tokena na skrypt lub asystenta, aby można było je zmieniać lub cofać osobno.

Środowiska pracy #

Token należy do jednego środowiska, w którym został utworzony. Każde żądanie odczytuje i zapisuje tylko to środowisko; w ścieżkach nie ma id środowiska. Token właściciela (środowisko zarządzające kilkoma agencjami) może działać na jednej z agencji przez nagłówek LanaChat-Workspace: ws_…; każdy inny token wysyłający ten nagłówek dostaje 403.

Uprawnienia #

Każdy endpoint wymienia potrzebne uprawnienie. To te, które zaznaczasz przy tworzeniu tokena:

• Wyłączenie Access AI configuration (can_engine) wyłącza też publikowanie, Advanced AI i raporty eksperymentów.
• can_chat, can_tracking i token owner są planowane: Console ich jeszcze nie oferuje.

Żądania i odpowiedzi #

• Ciała to JSON (Content-Type: application/json), w UTF-8. Uploady idą przez signed URL, nigdy przez samo API.
• Identyfikatory to ciągi znaków z prefiksem określającym typ: cr_ twórczyni, acc_ konto Telegram, pool_, sto_ story, br_ brain, scr_ skrypt, med_ media, fan_, conv_ konwersacja, msg_, lnk_ link, px_ pixel, mem_ członek, tok_ token.
• Czasy w ISO 8601 w UTC (2026-10-06T14:05:00Z). Dni w statystykach to dni UTC.
• Pieniądze w centach USD (amount_cents: 1900 to $19.00). Telegram Stars to liczby całkowite (stars: 250).
• PATCH zmienia tylko przesłane pola. PUT zastępuje cały obiekt.
• POST tworzący coś zwraca 201 z nowym obiektem; inne udane wywołania zwracają 200.

Paginacja #

Każda lista zwraca jedną stronę i kursor do następnej:

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 od 1 do 100, domyślnie 25.
• next_cursor to null na ostatniej stronie. Kursor jest nieprzejrzysty: zwracaj go tak, jak jest, nigdy nie twórz samodzielnie.
• Listy są sortowane od najnowszych, chyba że endpoint mówi inaczej.

Aby odczytać wszystkie strony, wykonuj pętlę aż next_cursor będzie 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")

Błędy #

Błąd zwraca status 4xx lub 5xx i zawsze takie samo ciało:

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

message to zwykłe zdanie po angielsku, które możesz pokazać użytkownikowi. W kodzie rozgałęzia się po code, nigdy po message.

Limity zapytań #

Każdy token może wysłać 600 zapytań na minutę. Każda odpowiedź zawiera RateLimit-Limit, RateLimit-Remaining i RateLimit-Reset (sekundy do resetu limitu). Po przekroczeniu limitu API zwraca 429 z nagłówkiem Retry-After. Wysyłanie wiadomości do fana jest też ograniczone limitami Telegrama: zobacz zasady puli.

Mały helper, który czeka i próbuje ponownie przy 429 i 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');
}

Używaj go wszędzie: await lanachat('GET', '/creators'), await lanachat('POST', '/links', { … }).

Idempotencja #

Wysyłaj nagłówek Idempotency-Key (dowolny unikalny ciąg do 255 znaków, UUID jest ok) przy każdym POST. Jeśli ten sam klucz wróci w ciągu 24 godzin, API zwróci pierwszy wynik zamiast wykonać operację dwa razy: błąd sieci nigdy nie wyśle wiadomości ani nie kupi pakietu dwa razy.

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}'

Ten sam klucz z innym ciałem zwraca 409. W shellu $(uuidgen) tworzy nowy klucz dla każdej akcji.

Webhooki #

Zamiast pytać API co minutę, pozwól LanaChat dzwonić do Ciebie. Webhook wysyła HTTPS POST do Twojego serwera, gdy fan napisze pierwszy raz, kupi, zostanie zwrócony, gdy media są gotowe lub konto traci połączenie. Każda dostawa jest podpisana (HMAC-SHA256) i ponawiana przez 24 godziny. Zdarzenia, payloady i sprawdzanie podpisu w Node i Python są w Webhooks.

MCP dla asystentów AI #

MCP to otwarty standard pozwalający asystentowi AI korzystać z narzędzi w aplikacji. Serwer MCP LanaChat pozwala Claude, Cursor lub dowolnemu klientowi MCP czytać Twoje twórczynie, tworzyć szkice skryptów, edytować szkic braina i czytać sprzedaż, z tym samym tokenem i uprawnieniami. W Claude Code jedno polecenie łączy go:

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

Konfiguracja dla każdego asystenta i lista narzędzi są w API & MCP.