API v2

API v2 ist eine strukturierte REST-API zur Verwaltung von Agenten und zum Erstellen individueller Chat-Erlebnisse. Sie ergänzt Agent-Verwaltung, Streaming-Chat, Unterhaltungsverlauf, Nachrichten-Feedback, Kontakte, Leads, Quellen, Einstellungen und Trainings-Endpunkte.

Für den API-Zugriff ist mindestens der Hobby-Tarif mit aktiver Abrechnung erforderlich.

Basis-URL

https://your-domain.com/api/v2

Authentifizierung

Außer beim Health-Check senden Sie Ihren Workspace-API-Schlüssel als Bearer-Token:

Authorization: Bearer YOUR_API_KEY

Erstellen und widerrufen Sie API-Schlüssel unter Einstellungen > API-Schlüssel.

Antwortformat

Die meisten erfolgreichen Antworten liefern entweder ein Ressourcenobjekt oder einen data-Umschlag zurück:

{
  "data": []
}

Listen-Endpunkte enthalten eine Cursor-Paginierung:

{
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 0
  }
}

Fehler verwenden ein strukturiertes error-Objekt:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Jede v2-Antwort enthält einen x-request-id-Header. Geben Sie diesen Wert an, wenn Sie sich bezüglich einer API-Anfrage an den Support wenden.

Umfang der Unterhaltungen

Schreibgeschützte Unterhaltungs-Endpunkte verwenden standardmäßig source=api_v2. Setzen Sie source=widget, um Widget- und Playground-Unterhaltungen zurückzugeben; Playground-Datensätze werden mit der Quelle widget gespeichert. Setzen Sie source=all, um API-v2-, Widget- und Playground-Unterhaltungen zurückzugeben. Die Ergebnisse bleiben stets auf den Agenten des authentifizierten Kontos beschränkt. Ein ungültiger source-Wert oder mehr als ein source-Abfrageparameter führt zu 400 VALIDATION_INVALID_BODY. Chat-Fortsetzung, Wiederholung, Feedback, Nachrichtenauflistung und nutzerbezogene Abfragen bleiben auf API-v2-Unterhaltungen beschränkt.

Health-Check

GET /api/v2/health

Der Health-Check erfordert keine Authentifizierung.

Erfolg: 200 OK

{
  "status": "ok",
  "timestamp": 1784332800
}

timestamp ist der aktuelle Unix-Zeitstempel in Sekunden.

Chat

POST /api/v2/agents/{agentId}/chat

Anfrage:

{
  "message": "What plans do you offer?",
  "conversationId": "optional-existing-conversation-id",
  "userId": "optional-user-id",
  "stream": true
}

Streaming-Antworten verwenden Server-Sent Events. Der Stream enthält die Ereignisse message-start, text-start, text-delta, text-end, message-metadata, finish und [DONE]. Bei einem Fehler im Stream oder im Completion-Hook wird ein error-Ereignis mit error.code gleich CHAT_STREAMING_ERROR gesendet; dieser nur für SSE geltende Protokollcode ist unabhängig vom strukturierten REST-Fehlerkatalog. message-metadata enthält bei erfolgreicher Persistierung die ID der Assistant-Nachricht sowie die Unterhaltungs-ID, die Nutzer-ID, den Abschlussgrund und die Nutzungsangaben. Der Wert messageId ist null, wenn keine Assistant-Nachricht persistiert wurde. Wenn die Antwort bei einer clientseitigen Aktion pausiert, sendet der Stream zusätzlich ein tool-call-Ereignis mit { "id", "name", "arguments" }; übermitteln Sie das Ergebnis an den Tool-Result-Endpunkt, um die Unterhaltung fortzusetzen — die Antwort auf diese Anfrage streamt die Fortsetzung.

Antworten ohne Streaming liefern:

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "..." }],
    "pendingToolCall": null,
    "metadata": {
      "userMessageId": "122",
      "conversationId": "abc123",
      "userId": "user_123",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

Bei Antworten ohne Streaming sind data.id und metadata.userMessageId numerische Nachrichten-IDs, die als Strings serialisiert werden, oder null, wenn die zugehörige Nachricht nicht persistiert wurde. metadata.userId ist die übergebene bzw. gespeicherte Nutzer-ID oder null. pendingToolCall ist null, es sei denn, die Antwort wurde bei einem clientseitigen Tool-Aufruf pausiert; in diesem Fall enthält es { "id", "name", "arguments" } für den Tool-Result-Endpunkt.

Endpunktübersicht

Feedback

Mit Feedback markieren Sie API-v2-Assistant-Nachrichten als positive, negative oder null. Das Anfrageschema, die Antwort und das Fehlerverhalten finden Sie unter Unterhaltungen, Nachrichten und Feedback.

Paginierung

Behandeln Sie Cursor als von der API zurückgegebene, undurchsichtige Tokens. Übergeben Sie den Wert pagination.cursor bei der nächsten Anfrage unverändert; konstruieren oder dekodieren Sie ihn nicht selbst.

Kontakte akzeptieren zusätzlich search. Leads akzeptieren die inklusiven ISO-8601-Datumsfilter createdAfter und createdBefore. Quellen akzeptieren sourceType mit web_crawl, file_upload, text_snippet oder qna_entry.

Cursor-Formate sind ein internes Implementierungsdetail. Clients müssen jeden Cursor als undurchsichtig behandeln und ihn unverändert übergeben, ohne ihn zu konstruieren oder zu dekodieren.

Häufige Fehler

Den vollständigen API-v2-Fehlerkatalog mit allen 27 deklarierten Codes, HTTP-Status, Auslösern und reservierten Codes finden Sie dort.

Referenz

• Fehlerkatalog
• Agenten und Einstellungen
• Unterhaltungen, Nachrichten, Wiederholungen und Feedback
• Quellen und Training
• Kontakte und Leads
• Instagram-Kanal

Nächste Schritte

• API-Schlüssel erstellen
• Identitätsprüfung einrichten
• API-v2-Fehler prüfen
• Agenten und Einstellungen verwalten
• Mit Unterhaltungen arbeiten
• Quellen und Training verwalten
• Kontakte und Leads verwalten
• Instagram-Kanal verwalten