# LanaChat API: Schnellstart, Authentifizierung und Fehler

_API · 8 Min. Lesezeit · Aktualisiert 2026-10-22 · https://lanachat.ai/guides/de/api-overview/_

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.

> Note: Dies ist die öffentliche API-Referenz. Endpunkte, die mit **Planned** markiert sind, sind der veröffentlichte Vertrag, auf dem das Backend basiert: Sie antworten noch nicht. Die [MCP-Verbindung](https://lanachat.ai/guides/de/api-mcp/) verwendet dieselben Zugriffstoken.

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

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

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

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

Das war’s: Jeder andere Endpunkt funktioniert genauso. Fertige Skripte finden Sie in [API quick recipes](https://lanachat.ai/guides/de/api-recipes/).

## Alle Ressourcen

| Resource | Was sie abdeckt | Anleitung |
|---|---|---|
| Workspace | `GET /workspace`: der Workspace und die Berechtigungen des Tokens | Diese Seite |
| Creators | Creatorinnen, Identität, Persona und Setup-Fortschritt | [Creators](https://lanachat.ai/guides/de/api-creators/) |
| Telegram accounts | Konten, Pools, Pool-Einstellungen und Stories | [Telegram accounts](https://lanachat.ai/guides/de/api-telegram-accounts/) |
| AI Brains | Brains, Entwürfe, Veröffentlichung, Versionen und der Playground | [AI Brains](https://lanachat.ai/guides/de/api-ai-brains/) |
| Scripts | Skripte, Schritte und Ordner | [Scripts](https://lanachat.ai/guides/de/api-scripts/) |
| Vault | Medien, Ordner und signierte Uploads | [Vault](https://lanachat.ai/guides/de/api-vault/) |
| Fans and conversations | Fans, Listen, Verkäufe eines Fans, Nachrichten, Übernahme | [Conversations](https://lanachat.ai/guides/de/api-conversations/) |
| Tracking | Links, Domains, Pixel, Events und Statistiken | [Tracking](https://lanachat.ai/guides/de/api-tracking/) |
| Billing | Guthaben, Buchhaltung, Einzahlungen, Lizenzen, Auszahlungen, Rechnungen | [Billing](https://lanachat.ai/guides/de/api-billing/) |
| Team | Mitglieder, Rollen und Zugriffstoken | [Team](https://lanachat.ai/guides/de/api-team/) |
| Webhooks | Ereignisse, die an Ihren Server gesendet werden, Signaturen und Wiederholungen | [Webhooks](https://lanachat.ai/guides/de/api-webhooks/) |
| MCP | Der Server für KI-Assistenten und seine Werkzeuge | [MCP](https://lanachat.ai/guides/de/api-mcp/) |

## Basis-URL und Versionen

Jeder Pfad in diesen Anleitungen ist relativ zu:

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

```text
Authorization: Bearer lc_live_8f2c1d0e9b7a4c6f
```

- Erstellen, bearbeiten, rotieren und widerrufen Sie Tokens in **Users › API & MCP** oder mit den [Token-Endpunkten](https://lanachat.ai/guides/de/api-team/). 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:

| Berechtigung | In der Console | Ermöglicht |
|---|---|---|
| `can_setup` | Workspace-Setup verwalten | Creatorinnen, Medien, Telegram-Konten, Skripte und Teammitglieder |
| `can_engine` | Zugriff auf KI-Konfiguration | AI Brain-Entwürfe, KI-Einstellungen und Tests von Skripten |
| `can_publish` | AI Brain-Entwürfe veröffentlichen | Veröffentlichung eines Brain-Entwurfs (benötigt `can_engine`) |
| `can_ai_test` | Erweiterte KI-Entwürfe testen | Testen von Entwürfen mit Advanced AI (nur Owner-Workspace) |
| `can_ai_tune` | Erweiterte KI-Einstellungen anpassen | Ändern der Sensitivitätseinstellungen von Advanced AI (nur Owner-Workspace) |
| `can_ai_publish` | Erweiterte KI-Profile veröffentlichen | Veröffentlichung von Profilen mit Advanced AI (nur Owner-Workspace) |
| `can_commercial_reports` | Kommerzielle Experimentberichte lesen | Experimente und deren Prüfberichte (nur Owner-Workspace) |
| `can_fan_read` | Fans und Konversationen lesen | Fans, Konversationen und Nachrichten, nur lesend |
| `can_fan_import` | Fan-Historie importieren | Import von vergangenen Fans und Nachrichten |
| `can_sales_read` | Verkäufe lesen | Verkäufe, Statistiken und Dashboard-Zahlen |
| `can_chat` | Neu: Chat mit Fans | Nachrichten senden, Reaktionen und Übernahme einer Konversation |
| `can_tracking` | Neu: Tracking verwalten | Links, Domains, Pools, Pixel und Events |
| `owner` | Owner-Token | Abrechnung, Rollen, Webhooks und Zugriffstoken; nur der Workspace-Besitzer kann es erstellen |

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

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

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

## Fehler

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

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

| Status | `code` | Wann |
|---|---|---|
| 400 | `invalid_request` | Ein Feld fehlt oder hat das falsche Format; `message` sagt welches |
| 401 | `unauthorized` | Kein Token oder ein widerrufenes bzw. abgelaufenes Token |
| 402 | `insufficient_balance` | Das Guthaben reicht für einen Kauf nicht aus |
| 403 | `forbidden` | Das Token hat nicht die benötigte Berechtigung für den Endpunkt |
| 404 | `not_found` | Die ID existiert in diesem Workspace nicht |
| 409 | `conflict` | Die Änderung würde eine Regel verletzen (ein doppelter Slug, das letzte Versandkonto einer Creatorin) |
| 429 | `rate_limited` | Zu viele Anfragen; warten Sie `Retry-After` Sekunden |
| 500 | `server_error` | Fehler auf unserer Seite; versuchen Sie es später mit demselben `Idempotency-Key` erneut |

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

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

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

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.

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

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

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

## Verwandte Artikel

- [API Schnellrezepte: kopieren, einfügen, ausführen](https://lanachat.ai/guides/de/api-recipes/)
- [API & MCP: Einen KI-Assistenten verbinden](https://lanachat.ai/guides/de/api-mcp/)
- [API: Webhooks, Events und Signaturen](https://lanachat.ai/guides/de/api-webhooks/)