Skip to main content
Für Chats mit einem Agenten gibt es zwei Wege. Chat Completions (POST /v1/chat/completions) ist zustandslos: Sie senden den bisherigen Verlauf bei jedem Aufruf im messages-Array mit. Konversationen speichern den Verlauf dagegen serverseitig und laufen wie ein Chat in der App — einschließlich der Warteschlange für Code-Ausführung, wenn gerade keine Kapazität frei ist. Alle Endpunkte dieser Seite akzeptieren Ihren persönlichen API-Key (siehe Authentifizierung und Rollen). Die Beispiele nutzen die Base-URL https://<deine-instanz>-api.localmind.ai/v1; jeder Request trägt den Header Authorization: Bearer sk-….

​
Endpunkte

Beim Anlegen ist der Schrägstrich am Ende Pflicht: POST /v1/conversations/. Ohne ihn antwortet die API mit 405.
Zum Anlegen senden Sie agent_id und space_id, optional einen title. Beim Senden einer Nachricht ist message das einzige Feld im Body. Die synchrone Variante …/messages antwortet erst, wenn die Antwort fertig ist, mit role und content. Für längere Antworten — insbesondere solche mit Code-Ausführung — nutzen Sie …/messages-async: Die API antwortet sofort mit 202 und den Feldern run_id, user_message_id und conversation_id.
cURL
Umbenennen und Taggen einer Konversation ist nur in der App möglich. Eine laufende Wartezeit in der Warteschlange für Code-Ausführung können Sie per API-Key nicht abbrechen.

​
Auf eine Antwort warten

Nach messages-async läuft die Antwort im Hintergrund. Warten Sie dabei nicht auf das Ende des Runs: Muss die Antwort auf eine freie Code-Ausführung warten, meldet der Run sofort COMPLETED, und die Antwort läuft später in einem neuen Run weiter. Maßgeblich ist der Status der Konversation.
1

Nachricht senden und user_message_id merken

Senden Sie die Nachricht über POST /v1/conversations/{id}/messages-async und speichern Sie die user_message_id aus der 202-Antwort.
2

Status ohne Nachrichten abfragen

Fragen Sie GET /v1/conversations/{id}/state?include_messages=false ab. Ohne Nachrichten bleibt die Antwort klein. Relevant sind diese Felder:
  • active_run_id — ein Run arbeitet gerade an der Antwort; run_status ist dann QUEUED oder RUNNING.
  • sandbox_queue — die Antwort wartet auf eine freie Code-Ausführung. message_id ist die ID der künftigen Antwort, position der Platz in der Warteschlange der ganzen Instanz (1 = als Nächstes). Ist position null, lässt sich der Platz gerade nicht bestimmen — die Antwort ist damit nicht fertig.
  • active_run_resumes_message_id — der aktive Run setzt eine wartende Antwort fort.
3

Abfragen, bis die Antwort fertig ist

Die Antwort ist fertig, wenn active_run_id und sandbox_queue beide null sind. Fragen Sie alle paar Sekunden ab, solange active_run_id gesetzt ist, und alle 15–30 Sekunden, solange nur sandbox_queue gesetzt ist.
4

Antwort lesen

Lesen Sie die Antwort einmal über GET /v1/conversations/{id}/state ohne Option — die Antwort enthält dann die letzten 50 Nachrichten. Ihre Antwort ist die letzte Assistenten-Nachricht, deren parent_message_id der user_message_id aus Schritt 1 entspricht. Nehmen Sie nicht einfach die neueste Nachricht: In derselben Konversation können andere Antworten laufen. Ältere Nachrichten liefert bei Bedarf GET /v1/conversations/{id}/messages.
Auszug einer Antwort von GET …/state?include_messages=false, während die Antwort auf Platz 2 der Warteschlange wartet:
Auszug

​
Wartezeit ohne Code und Fehler

Eine Wartezeit in der Warteschlange kann ohne Code-Ausführung enden: wenn in der Konversation eine neue Nachricht eintrifft, wenn die maximale Wartezeit der Instanz erreicht ist oder wenn ein Administrator die Warteschlange abgeschaltet hat. Die Antwort trägt dann in metadata.widgets einen Eintrag info mit info_type sandbox_busy. Bei einem Fehler enthält die Konversation meist eine Nachricht mit metadata.error: true und dem Fehlercode in metadata.code. Gibt es keine Antwort-Nachricht, ist die Antwort ohne Ergebnis geendet, zum Beispiel wegen eines erreichten Credit-Limits. In Sonderfällen prüfen Sie über GET /v1/pipeline/{run_id}, ob der Run den Status FAILED hat.

​
Zugriff

Ein Key erreicht nur Konversationen, die seinem Besitzer gehören oder mit ihm geteilt wurden. Ist der Key auf andere Spaces beschränkt als den der Konversation, antwortet die API mit 403 — anders als beim stillen 404 anderer Ressourcen. Löschen setzt Schreibrechte im Space voraus. Der Status-Endpunkt GET /v1/conversations/{id}/state ist per API-Key neu in Version 1.6.0.

​
Verwandte Seiten

OpenAI-kompatibel

Zustandslose Chats über POST /v1/chat/completions.

Agenten

Agent-IDs finden und die Konfiguration lesen.

Authentifizierung und Rollen

Persönlicher API-Key, Space-Scope und Rollen.

Konventionen und Fehler

Pagination, Filter und das Fehlermodell.