Entwickler

REST-API

Mit der REST-API liest du Gespräche, Leads, Assistenten und Kennzahlen aus deinem Workspace und legst Leads aus eigenen Systemen an.

Wofür die API da ist

Die REST-API verbindet deinen Lymbe-Workspace mit deinen eigenen Systemen: CRM, Warenwirtschaft, Data-Warehouse oder ein eigenes Reporting. Du holst Gespräche und Leads ab, liest die Auswertung deiner Assistenten aus und legst Leads an, die zum Beispiel aus einem Formular auf deiner Website kommen.

Die API ist bewusst schlank: Sie liest fast nur. Assistenten, Gedächtnis und Abläufe richtest du im Portal ein, nicht über die API.

Voraussetzungen

Was	Details
Tarif	Ein Tarif mit API-Zugang. Welche Tarife das sind, siehst du unter Abrechnung. Ohne API-Zugang antworten die Endpunkte mit `403`.
Recht	Zum Anlegen von Schlüsseln brauchst du das Recht API-Schlüssel verwalten (siehe Team und Rollen).
API-Schlüssel	Unter Einstellungen → API Keys angelegt. Siehe Authentifizierung.

Basis-URL

Alle Endpunkte liegen unter /api/v1 auf der Adresse, unter der du dein Portal aufrufst. Die genaue Basis-URL zeigt dir die Seite Einstellungen → API Keys im Kasten „Schnellstart“. Hast du eine eigene Domain eingerichtet, funktioniert sie genauso.

Basis-URLtext

https://app.lymbe.ai/api/v1

Alle Endpunkte

Methode	Pfad	Zweck	Grenze
GET	`/verify`	Schlüssel prüfen, Workspace und Tarif anzeigen	–
GET	`/bots`	Aktive Assistenten auflisten	–
GET	`/conversations`	Gespräche auflisten	100/Std.
GET	`/conversations/{id}/messages`	Nachrichten eines Gesprächs	100/Std.
GET	`/leads`	Leads auflisten	100/Std.
POST	`/leads`	Lead anlegen	100/Std.
GET	`/analytics`	Kennzahlen eines Assistenten	–

Die Seiten Gespräche, Leads, Assistenten und Auswertung beschreiben jeden Endpunkt mit Feldern und Beispielen.

Deine erste Anfrage

curlbash

curl https://app.lymbe.ai/api/v1/verify \
  -H "x-api-key: lymbe_DEIN_SCHLUESSEL"

fetch (Node.js oder Server)javascript

const res = await fetch('https://app.lymbe.ai/api/v1/verify', {
  headers: { 'x-api-key': process.env.LYMBE_API_KEY },
});
const data = await res.json();
// { valid: true, tenant: { name: 'Beispiel GmbH', slug: 'beispiel-gmbh' }, plan: { name: '…' } }

Schlüssel gehören auf den ServerEin API-Schlüssel öffnet den Zugang zu allen Daten des Workspaces. Ruf die API nur von deinem Server aus auf, nie aus Browser-Code, der auf deiner Website läuft.

Grenzen

100 Anfragen pro Stunde je Schlüssel für Gespräche, Nachrichten und Leads (gleitendes Fenster). Wird es überschritten, kommt 429.
/verify, /bots und /analytics zählen nicht zu dieser Grenze.
Listen liefern höchstens 100 Einträge je Anfrage (Standard 50). Mit offset blätterst du weiter.
Wer innerhalb von 15 Minuten 60-mal einen falschen Schlüssel schickt, wird für diese Zeit gesperrt (429).

Nur die Gesprächsliste schickt die Kopfzeilen X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Zeit in Sekunden) mit.

Fehlercodes

Status	Bedeutung	Was tun
400	Anfrage ungültig, z. B. Pflichtfeld fehlt	Feld `details` in der Antwort lesen
401	`API key required` oder `Invalid API key`	Kopfzeile `x-api-key` prüfen, Schlüssel nicht widerrufen?
403	Tarif ohne API-Zugang oder Workspace nur lesbar (`NUR_LESEN`)	Tarif prüfen
404	Gespräch, Assistent oder Workspace nicht gefunden	Kennung prüfen; sie muss zu deinem Workspace gehören
429	Zu viele Anfragen oder Lead-Grenze erreicht	Warten, bis das Fenster frei wird; Anfragen bündeln
500	Fehler auf unserer Seite	Später erneut versuchen, sonst Support

Fehler kommen immer als JSON mit einem Feld error, zum Beispiel {"error":"Invalid API key"}.

Was die API nicht kann

Gespräche anlegen oder Nachrichten schreiben. Dafür gibt es das Widget.
Assistenten, Gedächtnis oder Abläufe ändern. Das geht im Portal.
Leads ändern oder löschen. Das geht im Lead-Posteingang.
Ereignisse aktiv senden. Für Meldungen in Echtzeit nimm die Benachrichtigungen je Assistent.

Weiter

Authentifizierung
API-Playground zum Ausprobieren ohne Code
Datenexport, wenn du einmalig alle Daten brauchst

NächsteAuthentifizierung