Dokumentation / API

REST-API-Referenz

Jeder Endpunkt befindet sich unter /api/v1 und authentifiziert sich mit einem API-Schlüssel aus Konsole → Integrationen. Schlüssel werden nur einmal angezeigt und können nur lesend oder lesend/schreibend sein; widerrufene Schlüssel funktionieren sofort nicht mehr.

Senden Sie den Schlüssel als Authorization: Bearer bfk_…. Fehler werden als Problem-Details-JSON mit einem code zurückgegeben, auf den Sie reagieren können.

GET/api/v1/meBereich: read

Zu welchem Workspace und Tarif ein Schlüssel gehört. Der einfache Weg, um zu prüfen, ob ein Schlüssel funktioniert.

curl -H "Authorization: Bearer bfk_…" \
  https://your-domain/api/v1/me

GET/api/v1/bots?page=1&pageSize=50Bereich: read

Listet die Bots des Workspace mit Status und Version auf.

GET/api/v1/bots/{botId}Bereich: read

Ein Bot: Status, Zeitzone, Version, letzter Fehler.

GET/api/v1/bots/{botId}/subscribers?q=&page=1&pageSize=50Bereich: read

Die Zielgruppe des Bots, durchsuchbar nach Name oder Benutzername.

GET/api/v1/bots/{botId}/logs?level=error&limit=50Bereich: read

Aktuelle Laufzeitprotokolle; filterbar nach Stufe.

GET/api/v1/bots/{botId}/analytics?days=30Bereich: read

Nachrichtenvolumen, Zustellfehler und Abonnentenwachstum pro Tag.

GET/api/v1/bots/{botId}/broadcastsBereich: read

Broadcast-Verlauf für den Bot.

GET/api/v1/bots/{botId}/logs/streamBereich: read

Live-Protokolle als Server-Sent Events. Einträge kommen als data:-Zeilen im LogEntry-JSON-Format; alle 15s ein Keepalive-Kommentar; der Server schließt die Sitzung nach 10 Minuten (erneut verbinden). EventSource kann keine Header senden, daher mit Fetch-basiertem Streaming konsumieren.

curl -N -H "Authorization: Bearer bfk_…"   https://your-domain/api/v1/bots/{botId}/logs/stream

POST/api/v1/bots/{botId}/broadcastsBereich: write

Erstellt und stellt einen Broadcast in einem einzigen Aufruf in die Warteschlange. Body: { "name": "…", "text": "…", "segmentId": "…" (optional) }. Die Zustellung erfolgt über dieselbe getaktete Pipeline wie Konsolen-Broadcasts; Ihr Tariflimit gilt.

curl -X POST -H "Authorization: Bearer bfk_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"June promo","text":"20% off until Friday"}' \
  https://your-domain/api/v1/bots/{botId}/broadcasts

Statuscodes und Limits

401 UNAUTHENTICATED — fehlender oder ungültiger Schlüssel.
403 FORBIDDEN — dem Schlüssel fehlt der Schreibbereich.
403 PLAN_LIMIT — Broadcast-Kontingent erreicht; die Meldung nennt die Obergrenze.
404 NOT_FOUND — falsche ID oder ein Bot, der zu einem anderen Workspace gehört.
Seitengrößen sind auf 100 begrenzt; Protokolllimits auf 200.

REST-API-Referenz

Statuscodes und Limits

Tiefer einsteigen

Versionen, Idempotenz und Fehler