OpenQCoreAI
Loslegen

API-Referenz · Sitzungen & Nachrichten

API für Chat-Sitzungen und Nachrichten

Erstellen, auflisten, umbenennen, anheften, als Favorit markieren und löschen von Chat-Sitzungen sowie Verwalten einzelner Nachrichten innerhalb dieser — einschließlich protokollierter Bearbeitungshistorie und Rückgängig-Funktion.

← Zurück zur DokumentationZu Endpunkten springen

Sitzungsendpunkte

POST /api/v1/sessions
GET /api/v1/sessions
GET /api/v1/sessions/{session_id}/messages
PATCH /api/v1/sessions/{session_id}
DELETE /api/v1/sessions/{session_id}

Nachrichtenendpunkte

GET /api/v1/messages/{message_id}
PATCH /api/v1/messages/{message_id}
GET /api/v1/messages/{message_id}/history
POST /api/v1/messages/{message_id}/undo
DELETE /api/v1/messages/{message_id}

Sitzung erstellen — Anfragekörper

json
{
  "title": "Untitled Chat",
  "kind": "chat",
  "folder_id": null,
  "agent_id": null,
  "metadata": {}
}

workspace_id wird vom Client im persönlichen Runtime nicht akzeptiert und muss andernfalls mit dem aktiven Workspace-Runtime-Kontext übereinstimmen — es wird niemals als willkürliche Client-Überschreibung verwendet.

Auflisten — Abfrageparameter & Antwort

kindagent_idpinnedlimit (Standard: 50, maximal 200)offset (Standard: 0)
json
{
  "items": [ { "id": "...", "title": "...", "pinned": false, "...": "..." } ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Sitzung aktualisieren (PATCH)

Mindestens ein Feld muss im Request-Body vorhanden sein — ein leerer PATCH wird abgelehnt.

Titelangeheftetmit Stern markiertals ungelesen markiert
json
{
  "pinned": true,
  "starred": false
}

Sitzungsverhalten

  • Eine Sitzung gehört genau einem Besitzer (einem Benutzer, optional auf einen Workspace beschränkt) — bestimmt durch den authentifizierten Anfragekontext, nicht durch die Client-Eingabe.
  • Das Löschen einer Sitzung ist ein Soft-Delete (deleted_at wird gesetzt); die Sitzung und ihre Nachrichten bleiben in der Datenbank, werden aber in allen Standardabfragen ausgeschlossen.
  • GET /sessions/{session_id}/messages gibt eine Nachrichtenanzahl zurück, die live aus den Nachrichten selbst berechnet wird, nicht aus einem gecachten Zähler.
  • Die Pfadparameter session_id und message_id werden als UUIDs validiert — eine fehlerhafte ID liefert einen klaren Validierungsfehler, keinen Serverfehler.
  • Demo-Sitzungen der Marketing-Website sind auf 3 pro Benutzer begrenzt und liefern 403, sobald dieses Limit erreicht ist.

Nachrichten-Bearbeitungshistorie & Rückgängig

Jede Bearbeitung des Inhalts oder Payloads einer Nachricht wird aufgezeichnet, bevor die Änderung angewendet wird, wobei die vorherige Version erhalten bleibt.

json
[
  {
    "id": "8f14e...",
    "old_content": "Original message text",
    "old_payload": null,
    "edited_at": "2026-07-30T16:40:00Z"
  }
]
  • Eine Nachricht kann nur vom Besitzer der Sitzung, zu der sie gehört, bearbeitet oder gelöscht werden.
  • Undo stellt die zuletzt aufgezeichnete Version wieder her und entfernt diesen Verlaufs­eintrag — es wird nicht weiter zurückgegangen als bis zur letzten Bearbeitung.
  • Das Bearbeiten oder Löschen einer Nachricht passt derzeit nicht das zwischengespeicherte Nachrichtenanzahl-Feld der Sitzung an; dieses spiegelt stattdessen immer die Live-Anzahl wider.

Fehlermodelle

400

Ungültige Anfrage — z. B. ein leerer PATCH-Body oder keine erkannten Änderungen.

401

Fehlende oder ungültige Authentifizierung.

404

Sitzung oder Nachricht nicht gefunden (oder nicht im Besitz des Aufrufers).

Beispiele

Sitzung erstellen

bash
curl -X POST "/api/v1/sessions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Chat", "kind": "chat"}'

Sitzung anheften

bash
curl -X PATCH "/api/v1/sessions/[session_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

Nachricht bearbeiten

bash
curl -X PATCH "/api/v1/messages/[message_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"content": "Corrected message text"}'

Letzte Bearbeitung rückgängig machen

bash
curl -X POST "/api/v1/messages/[message_id]/undo" \
  -H "Authorization: Bearer [token]"