> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localmind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Konversationen

> Konversationen mit Verlauf per API-Key anlegen, Nachrichten senden und auf die Antwort eines Agenten warten.

Für Chats mit einem Agenten gibt es zwei Wege. [Chat Completions](https://docs.localmind.ai/api-reference/OpenAI-Kompatibel.md) (`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](https://docs.localmind.ai/core-functions/Werkzeuge.md#warteschlange-bei-voller-kapazität), wenn gerade keine Kapazität frei ist.

Alle Endpunkte dieser Seite akzeptieren Ihren persönlichen API-Key (siehe [Authentifizierung und Rollen](https://docs.localmind.ai/api-reference/Authentifizierung-und-Rollen.md)). Die Beispiele nutzen die Base-URL `https://<deine-instanz>-api.localmind.ai/v1`; jeder Request trägt den Header `Authorization: Bearer sk-…`.

## Endpunkte

| Methode | Pfad | Zweck |
| - | - | - |
| `POST` | `/v1/conversations/` | Konversation anlegen |
| `POST` | `/v1/conversations/search` | eigene Konversationen auflisten und filtern |
| `GET` | `/v1/conversations/{id}` | eine Konversation lesen |
| `DELETE` | `/v1/conversations/{id}` | Konversation löschen |
| `POST` | `/v1/conversations/{id}/messages` | Nachricht senden und auf die Antwort warten |
| `POST` | `/v1/conversations/{id}/messages-async` | Nachricht senden, sofort `202` |
| `GET` | `/v1/conversations/{id}/state` | Status: läuft gerade eine Antwort, wartet sie auf Code-Ausführung, letzte 50 Nachrichten |
| `GET` | `/v1/conversations/{id}/messages` | gesamter Verlauf |

> [!WARNING]
>
> 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`.

```bash cURL theme={null}
# Konversation anlegen
curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/conversations/" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "{agent_id}", "space_id": "{space_id}", "title": "Vertragsprüfung" }'

# Nachricht asynchron senden
curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/conversations/{id}/messages-async" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Fasse die Kündigungsfristen zusammen." }'
```

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:

```json Auszug theme={null}
{
  "active_run_id": null,
  "run_status": null,
  "active_run_resumes_message_id": null,
  "sandbox_queue": { "message_id": "6b2f0c1e-…", "position": 2 },
  "messages": []
}
```

### 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](https://docs.localmind.ai/api-reference/Authentifizierung-und-Rollen.md) 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](https://docs.localmind.ai/changelog/v1.6.0.md).

## Verwandte Seiten

> **[OpenAI-kompatibel](https://docs.localmind.ai/api-reference/OpenAI-Kompatibel.md)**
>
> Zustandslose Chats über `POST /v1/chat/completions`.

> **[Agenten](https://docs.localmind.ai/api-reference/Agenten.md)**
>
> Agent-IDs finden und die Konfiguration lesen.

> **[Authentifizierung und Rollen](https://docs.localmind.ai/api-reference/Authentifizierung-und-Rollen.md)**
>
> Persönlicher API-Key, Space-Scope und Rollen.

> **[Konventionen und Fehler](https://docs.localmind.ai/api-reference/Konventionen-und-Fehler.md)**
>
> Pagination, Filter und das Fehlermodell.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.