LanaChat API: Schnellstart, Authentifizierung und Fehler

Alles, was Ihr Team in der Console macht, kann Ihr Code auch tun. Die LanaChat API liest und ändert Ihren gesamten Workspace: Creatorinnen, Telegram-Konten, AI Brains, Skripte, den Vault, Fans und Konversationen, Tracking-Links, Abrechnung und Ihr Team. Es ist einfaches JSON über HTTPS, eine URL pro Ressource, mit denselben Berechtigungen wie die Console. Webhooks senden Ereignisse an Ihren Server, und der MCP-Server ermöglicht einem KI-Assistenten wie Claude oder Cursor, mit demselben Token in Ihrem Workspace zu arbeiten.

Was Sie bauen können #

• Ein Sales-Dashboard in Ihren eigenen Tools: heutiger Umsatz pro Creatorin, pro Link, pro Quelle.
• Benachrichtigungen in Slack oder Telegram, wenn ein Fan kauft, wenn eine Konversation überprüft werden muss oder wenn ein Konto die Verbindung verliert.
• Ein Setup-Skript, das eine Creatorin hinzufügt, ihre Konten verbindet, ihren Vault hochlädt und ihr erstes Skript schreibt.
• Eine Tracking-Pipeline: Erstellen Sie einen Link pro Anzeige, lesen Sie Klicks, Konversationen und Käufer jede Stunde aus.
• Einen KI-Assistenten, der Skripte und Persona-Änderungen für Ihre Überprüfung entwirft, über MCP.

Schnellstart in 5 Minuten #

1. Öffnen Sie in der Console Users › API & MCP und klicken Sie auf Create token.
2. Benennen Sie es (zum Beispiel „Reporting script“), wählen Sie Custom permissions und aktivieren Sie, was benötigt wird, z. B. Read fans and conversations und Read sales.
3. Speichern Sie, dann klicken Sie auf Copy token. Das Token wird nur einmal angezeigt.

4. Bewahren Sie es in einer Umgebungsvariable auf, damit es nie im Code steht:

export LANACHAT_TOKEN="lc_live_8f2c1d0e9b7a4c6f"

5. Machen Sie Ihren ersten Aufruf. Er gibt Ihren Workspace und die Berechtigungen des Tokens zurück:

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

Das war’s: Jeder andere Endpunkt funktioniert genauso. Fertige Skripte finden Sie in API quick recipes.

Alle Ressourcen #

Basis-URL und Versionen #

Jeder Pfad in diesen Anleitungen ist relativ zu:

https://api.lanachat.ai/v1

Die Version steht im Pfad. Eine breaking change erhält eine neue Version (/v2); neue Felder und Endpunkte werden ohne Ankündigung zu /v1 hinzugefügt, ignorieren Sie also unbekannte Felder.

Authentifizierung #

Jede Anfrage trägt Ihr Token im Header Authorization, nach dem Wort Bearer:

Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f

• Erstellen, bearbeiten, rotieren und widerrufen Sie Tokens in Users › API & MCP oder mit den Token-Endpunkten. Nur der Workspace-Besitzer und Agenturinhaber können diese Seite öffnen.
• Ein Token wird nur einmal angezeigt, wenn Sie es erstellen. Speichern Sie es wie ein Passwort; Rotate oder Revoke Sie es auf derselben Seite.
• Eine Anfrage ohne gültiges Token antwortet mit 401. Ein Token ohne die benötigte Berechtigung für einen Endpunkt antwortet mit 403.
• Tokens gehören nie in eine URL oder in Browser-Code: Rufen Sie die API von Ihrem Server aus auf.
• Verwenden Sie pro Skript oder Assistent ein eigenes Token, damit jedes einzeln geändert oder widerrufen werden kann.

Workspaces #

Ein Token gehört zu genau einem Workspace, dem, in dem es erstellt wurde. Jede Anfrage liest und schreibt nur in diesem Workspace; es gibt keine Workspace-ID in den Pfaden. Ein Owner-Token (der Workspace, der mehrere Agenturen verwaltet) kann mit dem Header LanaChat-Workspace: ws_… für eine seiner Agenturen handeln; jedes andere Token, das diesen Header sendet, erhält 403.

Berechtigungen #

Jeder Endpunkt listet die benötigte Berechtigung auf. Das sind die, die Sie beim Erstellen eines Tokens ankreuzen:

• Das Deaktivieren von Access AI configuration (can_engine) deaktiviert auch Veröffentlichung, Advanced AI und Experimentberichte.
• can_chat, can_tracking und das owner-Token sind geplant: Die Console bietet sie noch nicht an.

Anfragen und Antworten #

• Bodies sind JSON (Content-Type: application/json), in UTF-8. Uploads erfolgen über eine signierte URL, niemals direkt über die API.
• IDs sind Strings mit einem Präfix, das angibt, was sie sind: cr_ Creatorin, acc_ Telegram-Konto, pool_, sto_ Story, br_ Brain, scr_ Skript, med_ Medium, fan_, conv_ Konversation, msg_, lnk_ Link, px_ Pixel, mem_ Mitglied, tok_ Token.
• Zeiten sind ISO 8601 in UTC (2026-10-06T14:05:00Z). Tage in Statistiken sind UTC-Tage.
• Geldbeträge sind in US-Cent (amount_cents: 1900 sind $19,00). Telegram Stars sind ganze Zahlen (stars: 250).
• PATCH ändert nur die gesendeten Felder. PUT ersetzt das ganze Objekt.
• Ein POST, das etwas erstellt, antwortet mit 201 und dem neuen Objekt; andere erfolgreiche Aufrufe antworten mit 200.

Pagination #

Jede Liste antwortet mit einer Seite und einem Cursor zur nächsten:

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 ist 1 bis 100, standardmäßig 25.
• next_cursor ist null auf der letzten Seite. Ein Cursor ist undurchsichtig: Geben Sie ihn unverändert zurück, bauen Sie ihn nie selbst.
• Listen sind standardmäßig nach neuestem Eintrag sortiert, außer der Endpunkt sagt etwas anderes.

Um alle Seiten zu lesen, wiederholen Sie, bis next_cursor null ist:

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

Fehler #

Ein Fehler antwortet mit einem 4xx- oder 5xx-Status und immer demselben Body:

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

message ist ein einfacher englischer Satz, den Sie einer Person zeigen können. Verzweigen Sie Ihren Code nach code, niemals nach message.

Rate Limits #

Jedes Token darf 600 Anfragen pro Minute senden. Jede Antwort enthält RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Sekunden bis zum Zurücksetzen des Fensters). Über dem Limit antwortet die API mit 429 und einem Retry-After-Header. Das Senden einer Nachricht an einen Fan unterliegt auch den eigenen Limits von Telegram: siehe die Pool-Regeln.

Ein kleiner Helfer, der bei 429 und 5xx wartet und es erneut versucht:

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

Verwenden Sie ihn überall: await lanachat('GET', '/creators'), await lanachat('POST', '/links', { … }).

Idempotenz #

Senden Sie bei jedem Idempotency-Key einen POST-Header (beliebiger eindeutiger String bis zu 255 Zeichen, eine UUID ist ideal). Wenn derselbe Schlüssel innerhalb von 24 Stunden erneut kommt, antwortet die API mit dem ersten Ergebnis, anstatt die Arbeit doppelt zu machen: Ein Netzwerkfehler sendet so nie eine Nachricht oder kauft ein Paket zweimal.

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

Dasselbe Schlüssel mit anderem Body antwortet mit 409. In einer Shell erzeugt $(uuidgen) für jede neue Aktion einen frischen Schlüssel.

Webhooks #

Statt die API jede Minute abzufragen, lassen Sie LanaChat Sie anrufen. Ein Webhook sendet ein HTTPS-POST an Ihren Server, wenn ein Fan zum ersten Mal schreibt, kauft, eine Rückerstattung erfolgt, ein Medium bereit ist oder ein Konto die Verbindung verliert. Jede Zustellung ist signiert (HMAC-SHA256) und wird 24 Stunden lang wiederholt. Die Events, Payloads und die Signaturprüfung in Node und Python finden Sie in Webhooks.

MCP für KI-Assistenten #

MCP ist ein offener Standard, der einem KI-Assistenten erlaubt, Werkzeuge in einer App zu nutzen. Der MCP-Server von LanaChat ermöglicht Claude, Cursor oder jedem MCP-Client, Ihre Creatorinnen zu lesen, Skripte zu entwerfen, einen Brain-Entwurf zu bearbeiten und Ihre Verkäufe zu lesen, mit demselben Zugriffstoken und denselben Berechtigungen. In Claude Code verbindet ein Befehl ihn:

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

Die Konfiguration für jeden Assistenten und die Liste der Werkzeuge finden Sie in API & MCP.