API-Dokumentation

Übersicht der Lymbe AI REST-API: Base URL, Authentifizierung, Rate Limits, Pagination und Fehlerbehandlung.

Übersicht

Die Lymbe AI API ist eine RESTful API, mit der du programmatisch auf Bots, Gespräche, Leads und weitere Ressourcen zugreifen kannst. Alle Anfragen und Antworten verwenden JSON.

Base URL

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

Alle API-Endpunkte sind relativ zu dieser Base URL. HTTPS ist erforderlich – HTTP-Anfragen werden abgelehnt.

Authentifizierung

Jede Anfrage muss einen gültigen API-Key im X-API-Key Header enthalten. API-Keys erstellst du in deinem Dashboard unter Einstellungen → API-Keys.

curl -X GET "https://app.lymbe.ai/api/v1/bots" \
  -H "X-API-Key: lymbe_sk_abc123def456"

Rate Limits

Die API ist auf eine bestimmte Anzahl von Anfragen pro Stunde begrenzt, abhängig von deinem Plan:

Plan	Anfragen/Stunde	Burst-Limit
Free	100	10 pro Sekunde
Pro	1.000	50 pro Sekunde
Business	5.000	100 pro Sekunde
Enterprise	25.000	500 pro Sekunde

Bei Überschreitung des Limits erhältst du eine 429 Too Many Requests Antwort. Die Response-Header enthalten Informationen zum aktuellen Limit:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1710700800

Pagination

Endpunkte, die Listen zurückgeben, unterstützen Pagination über die Query-Parameter limit und offset:

Parameter	Typ	Standard	Beschreibung
limit	number	20	Anzahl der Ergebnisse pro Seite (max. 100)
offset	number	0	Anzahl der zu überspringenden Ergebnisse

pagination-response.jsonjson

{
  "data": [],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Fehler-Codes

Die API verwendet Standard-HTTP-Statuscodes. Fehlerantworten haben immer folgendes Format:

error-response.jsonjson

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Der angegebene API-Key ist ungültig oder abgelaufen.",
    "status": 401
  }
}

Status	Code	Beschreibung
400	VALIDATION_ERROR	Ungültige Eingabedaten – prüfe die Request-Parameter
401	INVALID_API_KEY	API-Key fehlt oder ist ungültig
403	INSUFFICIENT_SCOPE	Der API-Key hat nicht die erforderlichen Berechtigungen
404	NOT_FOUND	Die angeforderte Ressource wurde nicht gefunden
429	RATE_LIMIT_EXCEEDED	Rate Limit überschritten – versuche es später erneut
500	INTERNAL_ERROR	Interner Serverfehler – kontaktiere den Support

Verfügbare Endpunkte

Methode	Endpunkt	Beschreibung
GET	/api/v1/verify	API-Key validieren
GET	/api/v1/bots	Alle Bots auflisten
GET	/api/v1/conversations	Gespräche auflisten
GET	/api/v1/conversations/:id/messages	Nachrichten eines Gesprächs abrufen
GET	/api/v1/leads	Leads auflisten
POST	/api/v1/leads	Neuen Lead erstellen

Verbindung testen

Verwende den /verify Endpunkt, um deinen API-Key zu testen und Informationen über deinen Tenant abzurufen:

curl -X GET "https://app.lymbe.ai/api/v1/verify" \
  -H "X-API-Key: lymbe_sk_abc123def456"

verify-response.jsonjson

{
  "valid": true,
  "tenant": {
    "id": "t_abc123",
    "name": "Musterfirma GmbH",
    "slug": "musterfirma"
  },
  "plan": {
    "name": "Pro",
    "botsLimit": 5,
    "messagesLimit": 10000
  }
}

VorherigeJavaScript Events NächsteAuthentifizierung