API-Referenz

API-Schlüssel erstellen

Öffnen Sie im Dashboard den Bereich Entwicklerzugriff und klicken Sie auf Neuen Schlüssel generieren. Sie vergeben einen Namen und können optional ein Ablaufdatum setzen; ohne Datum läuft der Schlüssel nicht ab. Dafür brauchen Sie die Berechtigung, API-Schlüssel zu verwalten.

• Der vollständige Schlüssel wird nur einmal angezeigt, direkt nach dem Erstellen. Kopieren Sie ihn sofort: Kyros speichert nur einen Hash des Schlüssels und kann ihn später nicht erneut anzeigen.
• In der Liste erkennen Sie jeden Schlüssel an seinem Namen und seinem Präfix (beginnt mit sk_).
• Mit Zugriff widerrufen machen Sie einen Schlüssel sofort ungültig. Anwendungen, die ihn verwenden, erreichen die API danach nicht mehr.
• Ein Schlüssel gehört zu dem Arbeitsbereich, in dem Sie ihn erstellt haben, und funktioniert nur für die Assistenten dieses Arbeitsbereichs.

Mit dem Header X-API-Key authentifizieren

Senden Sie den Schlüssel bei jeder Anfrage im Header X-API-Key. Ein API-Schlüssel im Header Authorization: Bearer wird nicht erkannt; die Anfrage endet dann mit 401.

X-API-Key: IHR_API_SCHLUESSEL

Fehlt der Header oder ist der Schlüssel ungültig, abgelaufen oder widerrufen, antwortet die API mit 401.

Alle Endpunkte liegen unter dem Pfad /api/v1/harness/. In den Beispielen steht https://API-HOST als Platzhalter für den Host. Den API-Host erfragen Sie über die Kontaktseite. ASSISTENT_ID steht für die ID Ihres Assistenten (eine UUID).

Eine Nachricht senden: der Chat-Endpunkt

POST /api/v1/harness/ASSISTENT_ID/chat führt eine Gesprächsrunde aus: Sie senden eine Nachricht, der Assistent antwortet. Der Request-Body ist JSON mit zwei Feldern:

• message (Pflicht, nicht leer) – die Nachricht an den Assistenten.
• thread_id (optional) – die thread_id einer früheren Antwort, um das Gespräch fortzusetzen. Ohne sie beginnt ein neues Gespräch; eine unbekannte ID startet ebenfalls ein neues.

curl -X POST "https://API-HOST/api/v1/harness/ASSISTENT_ID/chat" \
  -H "X-API-Key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{"message": "Wie lange dauert der Versand nach Österreich?"}'

Beispielantwort (gekürzt; Inhalte und Zahlen sind erfunden, „beispiel.de“ steht für einen Beispiel-Shop):

{
  "thread_id": "THREAD_ID",
  "message_id": "MESSAGE_ID",
  "answer": "Nach Österreich liefern wir in 3–5 Werktagen. Die Versandkosten finden Sie auf unserer Versandseite.",
  "citations": [
    {
      "source_id": 1,
      "url": "https://www.beispiel.de/versand",
      "name": "Versand & Lieferung"
    }
  ],
  "contexts": ["…"],
  "tool_calls": [
    {
      "tool_call_id": "TOOL_CALL_ID",
      "tool_name": "research",
      "args": { "query": "Versanddauer Österreich" },
      "result_preview": "…"
    }
  ],
  "usage": {
    "input_tokens": 2140,
    "output_tokens": 38,
    "total_tokens": 2178,
    "duration_ms": 2350
  }
}

Die Felder der Antwort:

• thread_id – die Gesprächs-ID; senden Sie sie mit der nächsten Nachricht zurück.
• message_id – die ID der Antwortnachricht (kann null sein).
• answer – der vollständige Antworttext.
• citations – die Quellen aus Ihrer Wissensdatenbank, auf die sich die Antwort stützt, jeweils mit source_id, url und name; leer, wenn keine Quelle verwendet wurde.
• contexts – die Textpassagen, die der Assistent in dieser Runde aus der Wissensdatenbank gelesen hat.
• tool_calls – die Werkzeuge, die der Assistent aufgerufen hat (tool_call_id, tool_name, args, result_preview).
• usage – Tokens (input_tokens, output_tokens, total_tokens) und Dauer in Millisekunden (duration_ms).

Was für API-Anfragen gilt

Die Antwort wird nicht gestreamt: Die API antwortet erst, wenn der Assistent fertig ist, und liefert den ganzen Text in einem Stück. Für API-Anfragen gelten dieselben Einstellungen wie im Chat-Widget – Modell, Anweisungen und Wissensdatenbank des Assistenten. Eingehende Nachrichten durchlaufen dieselbe Inhaltsmoderation, und jede Nachricht verbraucht Credits wie im Widget.

Weitere Endpunkte

• GET /api/v1/harness/ASSISTENT_ID/chat/THREAD_ID/messages – liefert den Verlauf eines Gesprächs (thread_id, messages, card_actions).
• POST /api/v1/harness/ASSISTENT_ID/kb/search – durchsucht die Wissensdatenbank des Assistenten ohne Modellaufruf (Body: query, optional limit u. a.); wird nicht abgerechnet und legt kein Gespräch an.
• GET /api/v1/harness/ASSISTENT_ID/kb/documents – listet die eingelesenen Dokumente der Wissensdatenbanken des Assistenten mit Status; filterbar über q und status, seitenweise über skip und limit.

Fehlercodes

• 401 – Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
• 400 – der Assistent ist nicht aktiv, oder die ID gehört zu einem Assistenten, der diese API nicht unterstützt.
• 403 – Ihr Tarif enthält kein Modell, mit dem der Assistent antworten kann.
• 404 – unbekannte Assistenten-ID; beim Verlauf auch ein unbekanntes Gespräch.
• 422 – der Request-Body ist ungültig, zum Beispiel fehlt message oder ist leer.
• 429 – ein Nutzungslimit Ihres Tarifs ist erreicht, zum Beispiel die Credits.
• 502 – die Gesprächsrunde konnte nicht abgeschlossen werden.

Ohne eigenen API-Client

Sollen nur Daten aus dem Gespräch in Ihr System fließen, brauchen Sie die REST-API nicht unbedingt: Die Aktionen einer interaktiven Card (Beta) können Ihre eigene API aufrufen, eine Einsendung speichern, eine Chat-Nachricht senden oder einen Link öffnen. Für die reine Einbettung des Chat-Widgets genügt die Einbetten-Anleitung; Einbau-Anleitungen für einzelne Plattformen finden Sie unter Integrationen.