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

_API · 8 min czytania · Zaktualizowano 2026-10-22 · https://lanachat.ai/guides/pl/api-overview/_

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.

> Note: To jest publiczna dokumentacja API. Endpointy oznaczone **Planned** to opublikowany kontrakt, na którym opiera się backend: jeszcze nie odpowiadają. Połączenie [MCP](https://lanachat.ai/guides/pl/api-mcp/) używa tych samych tokenów dostępu.

## 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](https://lanachat.ai/guides/pl/api-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:

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

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

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

To wszystko: każdy inny endpoint działa tak samo. Gotowe skrypty znajdziesz w [API quick recipes](https://lanachat.ai/guides/pl/api-recipes/).

## Wszystkie zasoby

| Resource | Co obejmuje | Przewodnik |
|---|---|---|
| Workspace | `GET /workspace`: środowisko i uprawnienia tokena | Ta strona |
| Creators | Twórczynie, tożsamość, persona i postęp konfiguracji | [Creators](https://lanachat.ai/guides/pl/api-creators/) |
| Telegram accounts | Konta, pule, ustawienia puli i stories | [Telegram accounts](https://lanachat.ai/guides/pl/api-telegram-accounts/) |
| AI Brains | Brains, szkice, publikacje, wersje i Playground | [AI Brains](https://lanachat.ai/guides/pl/api-ai-brains/) |
| Scripts | Skrypty, kroki i foldery | [Scripts](https://lanachat.ai/guides/pl/api-scripts/) |
| Vault | Media, foldery i podpisane uploady | [Vault](https://lanachat.ai/guides/pl/api-vault/) |
| Fans and conversations | Fans, listy, sprzedaż fana, wiadomości, przejęcia | [Conversations](https://lanachat.ai/guides/pl/api-conversations/) |
| Tracking | Linki, domeny, pixele, zdarzenia i statystyki | [Tracking](https://lanachat.ai/guides/pl/api-tracking/) |
| Billing | Saldo, księga, depozyty, licencje, wypłaty, faktury | [Billing](https://lanachat.ai/guides/pl/api-billing/) |
| Team | Członkowie, role i tokeny dostępu | [Team](https://lanachat.ai/guides/pl/api-team/) |
| Webhooks | Zdarzenia wysyłane do serwera, podpisy i ponowienia | [Webhooks](https://lanachat.ai/guides/pl/api-webhooks/) |
| MCP | Serwer dla asystentów AI i jego narzędzia | [MCP](https://lanachat.ai/guides/pl/api-mcp/) |

## Bazowy URL i wersje

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

```text
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`:

```text
Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f
```

- Twórz, edytuj, rotuj i cofaj tokeny w **Users › API & MCP** lub przez [endpointy tokenów](https://lanachat.ai/guides/pl/api-team/). 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:

| Permission | W Console | Daje |
|---|---|---|
| `can_setup` | Zarządzanie konfiguracją środowiska | Twórczynie, media, konta Telegram, skrypty i członkowie zespołu |
| `can_engine` | Dostęp do konfiguracji AI | Szkice AI Brain, ustawienia AI skryptów i testy |
| `can_publish` | Publikowanie szkiców AI Brain | Publikowanie szkicu braina (wymaga `can_engine`) |
| `can_ai_test` | Testowanie szkiców Advanced AI | Testowanie szkiców używających Advanced AI (tylko właściciel środowiska) |
| `can_ai_tune` | Regulacja ustawień Advanced AI | Zmiana czułości Advanced AI (tylko właściciel środowiska) |
| `can_ai_publish` | Publikowanie profili Advanced AI | Publikowanie profili używających Advanced AI (tylko właściciel środowiska) |
| `can_commercial_reports` | Odczyt raportów eksperymentów komercyjnych | Eksperymenty i ich raporty (tylko właściciel środowiska) |
| `can_fan_read` | Odczyt fans i konwersacji | Fans, konwersacje i wiadomości, tylko do odczytu |
| `can_fan_import` | Import historii fans | Import przeszłych fans i wiadomości |
| `can_sales_read` | Odczyt sprzedaży | Sprzedaż, statystyki i liczby na dashboardzie |
| `can_chat` | Nowość: czat z fans | Wysyłanie wiadomości, reakcji i przejmowanie konwersacji |
| `can_tracking` | Nowość: zarządzanie trackingiem | Linki, domeny, pule, pixele i zdarzenia |
| `owner` | Token właściciela | Rozliczenia, role, webhooki i tokeny dostępu; tworzy tylko właściciel środowiska |

- 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](https://lanachat.ai/guides/pl/api-vault/), 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:

```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` 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`:

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

## Błędy

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

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

| Status | `code` | Kiedy |
|---|---|---|
| 400 | `invalid_request` | Brak pola lub zły format; `message` mówi które |
| 401 | `unauthorized` | Brak tokena, token cofnięty lub wygasły |
| 402 | `insufficient_balance` | Saldo nie pokrywa zakupu |
| 403 | `forbidden` | Token nie ma wymaganego uprawnienia |
| 404 | `not_found` | Identyfikator nie istnieje w tym środowisku |
| 409 | `conflict` | Zmiana łamałaby regułę (duplikat slug, ostatnie konto wysyłające twórczyni) |
| 429 | `rate_limited` | Za dużo żądań; poczekaj `Retry-After` sekund |
| 500 | `server_error` | Błąd po naszej stronie; spróbuj ponownie z tym samym `Idempotency-Key` |

`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](https://lanachat.ai/guides/pl/api-telegram-accounts/).

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

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.

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

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](https://lanachat.ai/guides/pl/api-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:

```bash
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](https://lanachat.ai/guides/pl/api-mcp/).

## Powiązane artykuły

- [Szybkie przepisy API: kopiuj, wklej, uruchom](https://lanachat.ai/guides/pl/api-recipes/)
- [API i MCP: podłącz asystenta AI](https://lanachat.ai/guides/pl/api-mcp/)
- [API: webhooki, zdarzenia i podpisy](https://lanachat.ai/guides/pl/api-webhooks/)