Überblick

Quickchat AI stellt eine REST-API für den programmatischen Zugriff auf die Konfiguration Ihres KI-Agenten, die Wissensdatenbank, Konversationen, AI Actions und mehr bereit.

Authentifizierung

Alle API-Endpunkte verwenden Bearer-Token-Authentifizierung. Fügen Sie Ihren API-Token im Authorization-Header jeder Anfrage ein:

Authorization: Bearer <API_TOKEN>

Tokens werden im Quickchat Dashboard unter External Apps > API erstellt. Jeder Token ist ein JWT, das Ihre scenario_id enthält, sodass kein zusätzlicher Identifier-Header erforderlich ist.

• Token-Gültigkeit: 52 Wochen ab Erstellung
• Tokens können jederzeit über das Dashboard widerrufen werden
• Jeder Token ist auf einen einzelnen KI-Agenten (Szenario) beschränkt
• Das Erstellen von Tokens erfordert den Business-Tarif oder höher; in niedrigeren Tarifen ist die Option deaktiviert und der Endpunkt liefert 402 Payment Required

Hinweis

Der Echtzeit-Chat-Endpunkt (POST https://app.quickchat.ai/chat) akzeptiert denselben Bearer-Token wie der Rest dieser API, liegt aber außerhalb des Basis-Pfads /v1/api/ und erfordert scenario_id im Request-Body. Die vollständige Referenz finden Sie auf der Seite Chat.

Token-Scopes

API-Tokens werden mit einem von zwei Scopes erstellt:

Scope	Access Level	Description
read_all	Read-only	Kann alle Ressourcen lesen, aber nicht erstellen, aktualisieren oder löschen
write_all	Read + Write	Vollzugriff auf alle Endpunkte, einschließlich Schreiboperationen

• Tokens wird beim Erstellen im Dashboard unter External Apps > API ein Scope zugewiesen
• Der Scope write_all umfasst automatisch alle read_all-Berechtigungen
• Die Verwendung eines read_all-Tokens auf einem Schreib-Endpunkt liefert 403 mit "Insufficient token scope. Required: write_all"

Tipp

Verwenden Sie read_all-Tokens für Monitoring, Analytics und lesende Integrationen. Verwenden Sie write_all-Tokens nur, wenn Ihre Integration Ressourcen erstellen oder ändern muss.

Scope-Anforderungen nach Endpunktgruppe:

Endpoint Group	Read Operations	Write Operations
Chatbot Settings	read_all	write_all
Knowledge Base Settings	read_all	write_all
Articles	read_all	write_all
Article Language URLs	read_all	write_all
Tags	read_all	—
File Upload	—	write_all
Import External Content	—	write_all
Intercom Knowledge Base	read_all	write_all
Widget Configuration	read_all	write_all
Conversations	read_all	—
Conversation Metadata	read_all	write_all
Handoff Configuration	read_all	write_all
Conversation Rating	read_all	write_all
AI Actions	read_all	write_all

Basis-URL

Endpoint Group	Base URL
Knowledge Base, AI Actions, File Upload, Import, Chatbot Settings, Widget, Handoff, Conversation Rating	https://app.quickchat.ai/v1/api/
Conversations	https://app.quickchat.ai/v1/api_core/
Realtime Chat	https://app.quickchat.ai/chat

Rate-Limits

Rate-Limits werden pro Token und pro Endpunkt angewendet.

Tier	Limit	Applies To
READ	120 Anfragen/Min	GET- und List-Operationen
WRITE	60 Anfragen/Min	POST, PATCH, PUT, DELETE
HEAVY	20 Anfragen/Min	Datei-Uploads, Importe, Scraping

Wenn ein Rate-Limit überschritten wird, gibt die API HTTP 429 Too Many Requests zurück.

Paginierung

Listen-Endpunkte unterstützen Paginierung über Query-Parameter:

Parameter	Description
limit integer	Anzahl der Elemente pro Seite
offset integer	Anzahl der zu überspringenden Elemente

Paginierte Antworten folgen dieser Struktur:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Fehlerbehandlung

Alle Fehler werden als JSON im folgenden Format zurückgegeben:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Code	Description
400	BAD_REQUEST	Ungültige Eingabe oder fehlende Pflichtfelder
401	PERMISSION_DENIED	Ungültiger, abgelaufener oder widerrufener Token
402	PAYMENT_REQUIRED	Aktives Abonnement erforderlich
403	PERMISSION_DENIED	Dem Token fehlt der für diese Operation erforderliche Scope
404	NOT_FOUND	Ressource nicht gefunden
409	CONFLICT	Konflikt bei der Operation (z. B. gleichzeitige Änderung)
422	VALIDATION_ERROR	Request-Body hat die Schema-Validierung nicht bestanden
429	TOO_MANY_REQUESTS	Rate-Limit überschritten
500	UNKNOWN	Interner Serverfehler
503	SERVICE_UNAVAILABLE	Vorübergehende Nichtverfügbarkeit

---