API-Überblick

Jeder REST-Endpunkt von RolChat folgt einem einzigen Vertrag: dieselbe Basis-URL, derselbe Antwort-Envelope, dieselbe Paginierung, dieselbe Fehlerstruktur. Einmal gelernt, liest sich jede Endpunktgruppe in der Endpunktreferenz gleich.

Basis-URL und Versionierung

https://api.rolchat.com/api/v1/

Die Version steht im Pfad. Optionale Felder, neue Endpunkte oder neue Query-Parameter mit Standardwerten sind keine inkompatiblen Änderungen und erhöhen die Version nicht. Inkompatible Änderungen erscheinen als v2, und abgekündigte v1-Endpunkte funktionieren nach ihrer Ankündigung noch mindestens sechs Monate weiter (siehe Abkündigung).

Authentifizierung

Methode	Header	Verwendet für
JWT-Bearer	`Authorization: Bearer <access_token>`	Interaktive Sitzungen (die Web-App, mobile Apps)
API-Schlüssel	`Authorization: Bearer rcp_<secret>`	Aufrufe zwischen Maschinen, Plugin-API-Schlüssel
HMAC-Signatur	`X-RolChat-Signature: sha256=…`	Eingehende Webhooks aus Ihren Systemen, siehe Webhooks
Keine	-	Öffentliche Widget-Endpunkte (`/widget/…`, `/forms/…`), begrenzt auf Website und Origin

Verwenden Sie für Integrationen einen API-Schlüssel (ein persönliches Zugriffstoken). Schlüssel werden unter Einstellungen → Plugins → RolChat-API-Schlüssel erstellt, einmal angezeigt und nur als Hash gespeichert. Ein Schlüssel kann nie mehr als das Mitglied, das ihn erstellt hat: Seine Scopes werden bei jedem Aufruf mit den aktuellen Berechtigungen dieses Mitglieds abgeglichen. Unter Authentifizierung finden Sie JWT-Laufzeiten, den Header X-Account-Id und Sitzungen über mehrere Unternehmen.

Antwort-Envelope

Eine einzelne Ressource:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

Eine Liste:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

Antworten ohne Body (204 No Content nach einem Löschvorgang) enthalten trotzdem den Header X-Request-Id.

Ein Fehler:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code ist maschinenlesbares snake_case und der Wert, nach dem Sie verzweigen; message ist Englisch und für Logs gedacht. field und details sind vorhanden, wenn sie helfen, und enthalten nie personenbezogene Daten. Die API antwortet nie mit 200 und einem Array errors: Sind Fehler vorhanden, ist der Status 400 oder höher. Die vollständige Liste der Codes steht auf der Seite Fehler.

Paginierung

Listenendpunkte, die wachsen können, verwenden Cursor-Paginierung. Fragen Sie die erste Seite ohne Cursor ab und geben Sie danach den erhaltenen next_cursor unverändert zurück:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

limit ist standardmäßig 50 und auf 200 begrenzt; größere Werte werden mit 400 validation_failed abgelehnt.
Cursor sind undurchsichtig und laufen nach 24 Stunden ab (400 validation_failed mit code: cursor_expired).
Die Ergebnisse sind konsistent zum Snapshot der ersten Seite: Zwischen den Seiten gelöschte Datensätze verschwinden, neue Datensätze erscheinen erst, wenn Sie ohne Cursor neu beginnen.
Für Clients, die das bevorzugen, wird zusätzlich ein Header Link mit rel="next" und rel="prev" gesendet.

Idempotenz

Senden Sie bei jedem POST, PATCH oder DELETE einen Header Idempotency-Key (eine UUID oder ULID, bis 255 Zeichen):

Die erste Anfrage mit einem Schlüssel wird ausgeführt, und ihr Status und Body werden 24 Stunden gespeichert.
Eine Wiederholung mit demselben Schlüssel und demselben Body liefert die gespeicherte Antwort, ohne Nebenwirkungen erneut auszulösen.
Eine Wiederholung mit demselben Schlüssel, aber anderem Body wird mit 409 idempotency_key_conflict abgelehnt.

Verwenden Sie ihn für jeden Aufruf, der etwas mit Nebenwirkungen erzeugt: eine Nachricht, eine E-Mail oder eine SMS senden, einen Anruf starten, alles, was abgerechnet wird. GET-Anfragen sind immer idempotent und ignorieren den Header.

Rate Limits

Die Limits werden pro Minute gezählt und gelten pro Konto, API-Schlüssel oder Benutzer (bei Routen ohne Anmeldung pro IP-Adresse). Die Standardobergrenzen:

Kontingent	Standardlimit	Pro Minute
Anfragen ohne Anmeldung (nach IP)	60	pro IP
Angemeldeter Benutzer (Dashboard)	1 000	pro Benutzer
API-Schlüssel	1 000	pro Schlüssel
Öffentliche Widget-Endpunkte	60 pro Besucher und 600 pro Netzwerkadresse	pro Minute
Anmeldung (`/auth/login`)	5	pro IP
Eingehende Webhooks	300	pro Minute
MCP-Server	600	pro Minute
OAuth-Endpunkte	600	pro Minute

Die Obergrenzen sind die Plattform-Standardwerte und können vom Betreiber geändert werden; Ihr Tarif vervielfacht sie nicht, und Enterprise-Limits werden in Ihrem Vertrag vereinbart. Endpunkte mit Rate Limit liefern:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

Wird ein Limit überschritten, lautet die Antwort 429 mit code: rate_limited im Array errors und einem Header Retry-After in Sekunden. Warten Sie so lange, bevor Sie erneut aufrufen. Zehn fehlgeschlagene Anmeldungen sperren das Konto für 30 Minuten.

Größen und Timeouts

Kategorie	Maximaler Request-Body	Server-Timeout
Standard	1 MB	30 s
Nachricht mit Anhängen	25 MB	30 s
CSV-Import	50 MB	liefert `202` und läuft im Hintergrund
Bilder der Wissensdatenbank	10 MB	30 s
Bulk-API	10 MB	30 s
Suche	1 MB	10 s
KI-Anfragen	1 MB	60 s
Widget-Endpunkte	100 KB	30 s

Zu große Bodies erhalten 413 payload_too_large. Ein Upstream mit Zeitüberschreitung antwortet mit 504, code: upstream_timeout und einem Hinweis retry_after, wenn eine Wiederholung helfen kann.

Inhaltstypen, Datumsangaben und IDs

Anfragen und Antworten sind application/json; charset=utf-8. Datei-Uploads verwenden multipart/form-data; CSV-Exporte liefern text/csv. Ungültiges UTF-8 wird mit 400 validation_failed abgelehnt.
Zeitstempel sind ISO-8601 in UTC mit Millisekundengenauigkeit: 2026-04-20T14:23:45.123Z. Bei der Eingabe wird jeder ISO-8601-Offset akzeptiert und auf UTC normalisiert.
Kennungen sind undurchsichtige ULIDs oder UUIDs. Es gibt keine numerischen IDs, und E-Mail-Adressen oder Telefonnummern erscheinen nie in einer URL.

Mandantentrennung und Berechtigungen

Jede authentifizierte Anfrage läuft innerhalb eines Kontos. Eine Ressource, die zu einem anderen Konto gehört oder zu einer Website, die die Rolle des Aufrufers nicht abdeckt, antwortet mit 404 not_found statt 403, damit die Existenz von Datensätzen nie preisgegeben wird. Ein gültiges Token ohne die erforderliche Berechtigung (zum Beispiel contacts.delete) antwortet mit 403 forbidden. Manche Berechtigungen tragen ein Scope-Suffix (conversations.read:own, :team, :all), das einschränkt, was eine Liste liefert.

PATCH akzeptiert nur beschreibbare Felder. id, account_id, created_at, updated_at und Zustandsfelder wie resolved_at sind schreibgeschützt; wird eines davon gesendet, kommt 400 validation_failed mit details.forbidden_fields zurück. Zustandsänderungen laufen über eigene Aktionen wie POST /tickets/:id/resolve.

Jeder Schreibvorgang wird im Audit-Log des Kontos erfasst.

Header für Beobachtbarkeit

Jede Antwort enthält:

X-Request-Id: req_01HK…

Protokollieren Sie X-Request-Id. Danach fragt der Support als Erstes.

CORS

Der Origin des Browser-Dashboards ist https://app.rolchat.com. Öffentliche Widget-Endpunkte erlauben jeden Origin oder nur die Origins, die Sie für eine Website verifizieren. Server-zu-Server-Aufrufe mit einem API-Schlüssel unterliegen nicht CORS.

Abkündigung

Die Änderung wird im Änderungsprotokoll angekündigt, und der betroffene Endpunkt sendet ab dann Deprecation: true und einen Header Sunset mit dem Entfernungsdatum.
Öffentliche Endpunkte funktionieren nach der Ankündigung noch mindestens sechs Monate weiter.
Entfernt wird nur in einer neuen Hauptversion. Innerhalb von v1 sind Änderungen rein additiv.

Zustand

Jeder Dienst stellt /healthz (Liveness) und /readyz (Readiness) bereit.