Unterhaltungen und Nachrichten

Eine Unterhaltung ist ein Chat-Verlauf, also genau das, was Ihr Team in der App unter Chat History sieht. Sie beginnt mit einer Nachricht, das Modell antwortet, und Sie schicken weitere Nachrichten hinterher. Jeder hier beschriebene Request läuft im Namen des Benutzers, dem der API-Schlüssel gehört, mit denselben Zugriffsrechten, Kontingenten und Workspace-Regeln, die für diesen Benutzer im Browser gelten.

Alle Pfade sind relativ zu https://api.stickyprompts.com/api/v1. Request-Bodys sind JSON. Dateien laden Sie zuerst über die Datei-Endpunkte hoch und referenzieren sie anschließend über ihre ID.

So funktioniert der Chat

1. Starten Sie mit POST /conversation (wartet auf die vollständige Antwort) oder POST /conversation/stream (kehrt sofort zurück; die Antwort kommt über den WebSocket). Beide legen die Unterhaltung an und senden die erste Nachricht in einem einzigen Aufruf.
2. Folgenachrichten senden Sie mit POST /conversation/:id oder POST /conversation/:id/stream.
3. Modell, Stil oder Denkaufwand für spätere Runden ändern Sie mit PATCH /conversation/:id/model. Die Bodys von Folgenachrichten akzeptieren kein Modell: Die Unterhaltung merkt sich ihre Einstellungen für die „nächste Nachricht“.
4. Den Verlauf lesen Sie mit GET /conversation/:id (paginiert, neueste zuerst), eine Liste Ihrer Unterhaltungen liefert GET /conversation.
5. Den Fortschritt verfolgen Sie live über den WebSocket GET /conversation/:id/ws, oder Sie fragen GET /conversation/:id regelmäßig ab und lesen den status der KI-Nachricht.

Kennungen. Die meisten Endpunkte akzeptieren als :id entweder die numerische Unterhaltungs-ID oder den 8-stelligen slug. Die Freigabe-Endpunkte, das Löschen, die Genehmigung sowie der WebSocket- und der SSE-Stream akzeptieren nur die numerische ID; darauf weisen wir unten jeweils hin.

Das Message-Objekt

Wird von den Sende-Endpunkten ohne Streaming zurückgegeben, ist in GET /conversation/:id enthalten und kommt als data der WebSocket-Events vom Typ message.

{
  "ID": 90412,
  "CreatedAt": "2026-09-28T09:14:03.512Z",
  "UpdatedAt": "2026-09-28T09:14:09.871Z",
  "DeletedAt": null,
  "conversation_context_id": 5120,
  "ai_model_id": 12,
  "ai_model": { "ID": 12, "name": "Example Model", "stream_support": true, "...": "..." },
  "agent_id": null,
  "is_auto_model": false,
  "text": "Here are three subject lines for the Northwind Q4 newsletter: ...",
  "raw_text": "Here are three subject lines for the Northwind Q4 newsletter: ...",
  "parts": [
    { "id": "p1", "type": "text", "static": true, "text_part": { "text": "Here are three ...", "raw_text": "Here are three ..." } }
  ],
  "thinking": null,
  "isUser": false,
  "error_text": null,
  "error_id": null,
  "error_code": null,
  "mcp_approval_requests": null,
  "ai_style": "prompty",
  "status": "finished",
  "citations": null,
  "response_duration_ms": 6210,
  "type": "normal",
  "attachments": []
}

Status. thinking bedeutet, dass die Zeile der KI-Nachricht existiert, aber noch nichts generiert wurde; generating bedeutet, dass Teilausgaben eintreffen; finished bedeutet fertig. Auch eine fehlgeschlagene KI-Nachricht ist finished, dann mit gesetztem error_text und error_id. Prüfen Sie also diese Felder und nicht nur status. Benutzernachrichten sind immer finished.

Credits. Jedes Feld credits_used ist eine Dezimalzahl, die als JSON-String serialisiert wird, zum Beispiel "0.4213".

Nachrichten senden

Request-Body

POST /conversation und POST /conversation/stream akzeptieren alle unten aufgeführten Felder. Die Endpunkte für Folgenachrichten akzeptieren nur die Felder mit dem Vermerk „Folgenachricht“; alle anderen werden stillschweigend ignoriert. Der Binder verlangt zwar kein einziges Feld zwingend, senden Sie aber immer eine message und ein Modell.

Modellauswahl. auto_model_type hat Vorrang, danach ai_model_id, danach der Projektstandard (mit X-Project-ID). Trifft nichts davon zu, wird die Unterhaltung trotzdem angelegt, das Senden schlägt aber mit 503 {"error":"no AI model is selected, try reselecting model"} fehl. Senden Sie beim Start daher immer ein Modell oder einen Auto-Typ mit. Eine Modell-ID mit dem wörtlichen Wert "auto" gibt es nicht. Agenten-Chats und @agent-Erwähnungen verwenden das Modell des Agenten (Stil prompty, kein Denkaufwand). Das Modell muss nach den Regeln Ihres Workspace für Modellzugriff und Datenresidenz erlaubt sein, sonst schlägt das Senden mit 503 fehl.

Tools

Jeder Eintrag hat die Form { "name": ..., "use": true | false }. Mögliche Namen: web_search, image_generation, video_generation, speech_generation, music_generation, remote_mcp.

• Ein Tool erreicht das Modell nur, wenn das Modell es in seinen tools-Fähigkeiten aufführt. Andernfalls wird es stillschweigend ignoriert.
• remote_mcp benötigt zusätzlich "mcp_tool_id": <id>, die ID eines Ihrer konfigurierten Remote-MCP-Server. Fügen Sie pro Server einen eigenen Eintrag hinzu.
• Automatische Tool-Auswahl. Bei Modellen mit Tool-Unterstützung kann ein kleiner Klassifikator anhand der Nachricht web_search und image_generation (sowie die Codeausführung) einschalten, auch wenn Sie das nicht angefordert haben. Sobald Sie für ein Tool einen Eintrag senden, selbst {"name":"web_search","use":false}, fügt der Klassifikator dieses Tool nicht mehr hinzu. Über die Codeausführung entscheidet allein der Klassifikator.

POST /conversation

Legt eine Unterhaltung an, sendet die erste Nachricht und wartet auf die vollständige KI-Antwort, einschließlich aller Tool-Aufrufe. Die Antwort ist die fertige KI-Message; die ID der neuen Unterhaltung steht in deren conversation_context_id. Nach dem ersten Austausch erhält die Unterhaltung automatisch einen Namen. Der Endpunkt akzeptiert den oben beschriebenen Request-Body sowie den optionalen Header X-Project-ID.

curl -X POST https://api.stickyprompts.com/api/v1/conversation \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Draft three subject lines for the Northwind Q4 newsletter.",
    "ai_model_id": 12,
    "ai_style": "prompty",
    "tools": [{ "name": "web_search", "use": false }]
  }'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/conversation",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={
        "message": "Draft three subject lines for the Northwind Q4 newsletter.",
        "ai_model_id": 12,
        "ai_style": "prompty",
        "tools": [{"name": "web_search", "use": False}],
    },
    timeout=300,
)
r.raise_for_status()
reply = r.json()
if reply.get("error_id"):
    print("Failed:", reply["error_text"], reply["error_id"])
else:
    print(reply["conversation_context_id"], reply["text"])

const res = await fetch("https://api.stickyprompts.com/api/v1/conversation", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Draft three subject lines for the Northwind Q4 newsletter.",
    ai_model_id: 12,
    ai_style: "prompty",
    tools: [{ name: "web_search", use: false }],
  }),
});
const reply = await res.json();
console.log(reply.conversation_context_id, reply.error_id ?? reply.text);

Antwort. 200 mit der KI-Message (siehe das Message-Objekt). Soll die KI nicht antworten (eine Team-Unterhaltung mit mehreren Mitgliedern ohne @ai- oder Agenten-Erwähnung), lautet der Body stattdessen 200 {"conversation_context_id": 5120}.

Fehler

Fällt der Anbieter mitten in der Generierung aus, wird die KI-Nachricht trotzdem mit error_text und error_id gespeichert, und Sie können sie mit POST /conversation/:id/retry erneut ausführen.

POST /conversation/stream

Gleiche Header und gleicher Body wie bei POST /conversation, der Endpunkt kehrt aber zurück, sobald die Benutzernachricht gespeichert ist. Die Generierung läuft im Hintergrund weiter, und die Antwort kommt über den WebSocket oder per Polling.

{ "conversation_context_id": 5120 }

Fehler, die schon vor dem Speichern der Benutzernachricht auffallen (Kontingent 429, ungültiger Agent, kein Modell ausgewählt, eingeschränktes Modell, Sperre wegen sensibler Daten), kommen weiterhin synchron zurück, in derselben Form wie oben. Fehler nach der 200 (Modell- oder Tool-Auswahl, Abruf aus der Wissensdatenbank, Fehler beim Anbieter) werden nur als WebSocket-Event error_message gemeldet und an einer KI-Nachricht mit error_text und error_id gespeichert.

Die Antwort abrufen

• WebSocket (empfohlen). Verbinden Sie sich mit GET /conversation/{conversation_context_id}/ws. Events, die vor Ihrem Verbindungsaufbau entstehen, werden gepuffert und dem ersten Client nachgeliefert. Wenn Sie sich direkt nach der 200 verbinden, geht also nichts verloren.
• Polling. Rufen Sie GET /conversation/:id?page=1&size=2 auf und lesen Sie die neueste KI-Nachricht (isUser: false, die erste in der Liste, da die neuesten zuerst kommen). Die KI-Nachricht wird mit status: "thinking" angelegt und bei jedem Chunk gespeichert. Sie sehen also generating mit wachsendem text und schließlich finished. Hören Sie bei finished auf und prüfen Sie error_id. Direkt nach der 200 existiert die KI-Nachricht unter Umständen noch nicht; ist die neueste Nachricht noch Ihre eigene, hat die Generierung noch nicht begonnen.

Echtes Streaming in Echtzeit gibt es nur bei Modellen mit stream_support: true. Bei anderen Modellen erscheint die Antwort in einem Stück, sobald sie fertig ist.

POST /conversation/:id

Sendet eine Folgenachricht und wartet auf die KI-Antwort. Modell, Stil und Denkaufwand stammen aus den next_message_*-Einstellungen der Unterhaltung; ändern Sie diese vorher mit PATCH /conversation/:id/model.

curl -X POST https://api.stickyprompts.com/api/v1/conversation/5120 \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Make the second one shorter." }'

Antwort. Wie bei POST /conversation: 200 mit der KI-Message oder 200 {"conversation_context_id": ...}, wenn die KI nicht antwortet. Läuft in der Unterhaltung ein aktiver Modellvergleich, geht die Nachricht parallel an jeden Thread, und die Antwort ist ein JSON-Array aus KI-Messages, eine pro Thread.

Fehler. Wie bei POST /conversation, zusätzlich 404 {"error":"Conversation not found"}. Senden dürfen nur der Inhaber sowie Benutzer oder Teams mit chat_contribute; alle anderen erhalten 503 {"error":"you are not allowed to send messages in this conversation"}.

POST /conversation/:id/stream

Wie POST /conversation/:id, gibt aber sofort 200 {"conversation_context_id": <id>} zurück. Den Fortschritt verfolgen Sie über den WebSocket oder per Polling, wie bei POST /conversation/stream. Bei einem aktiven Modellvergleich streamt jeder Thread auf den WebSocket der übergeordneten Unterhaltung.

Wann die KI antwortet

Die KI beantwortet eine Nachricht, wenn mindestens einer dieser Fälle zutrifft:

• nur ein einziger Benutzer darf in der Unterhaltung mitschreiben (der Normalfall, auch bei jeder Unterhaltung, die mit einem API-Schlüssel und ohne team_id angelegt wurde);
• der Text enthält @ai (Groß- und Kleinschreibung wird beachtet);
• es handelt sich um einen Agenten-Chat;
• der Text erwähnt (@mentions) das Tag eines Agenten, der in die Unterhaltung eingeladen wurde.

Andernfalls wird die Nachricht als einfache Benutzernachricht gespeichert, die die anderen Teilnehmer sehen, und der Endpunkt gibt 200 {"conversation_context_id": <id>} zurück, ohne ein Modell aufzurufen. Das gilt auch für die Endpunkte ohne Streaming.

Agenten in einer Unterhaltung

• Mit agent_id beim Anlegen wird die Unterhaltung zum Agenten-Chat. Dessen Modell lässt sich später nicht mehr ändern.
• In einer Unterhaltung mit nur einem Benutzer leitet @tag die Runde an Ihren eigenen Agenten mit diesem Tag oder an einen mit Ihnen geteilten Agenten (bei gleichem Tag haben Ihre eigenen Agenten Vorrang). In einer Unterhaltung mit mehreren Benutzern lassen sich nur Agenten erwähnen, die mit invited_agent_ids oder POST /conversation/:id/agents eingeladen wurden.
• Der antwortende Agent wird an der KI-Nachricht vermerkt (agent_id, agent).

Streaming

GET /conversation/:id/ws

Ein WebSocket, der jede Aktualisierung der Unterhaltung überträgt. Verbinden Sie sich mit wss://api.stickyprompts.com/api/v1/conversation/5120/ws und senden Sie beim Upgrade-Request den Header Authorization: Bearer STICKY-API-... mit. WebSocket-Objekte im Browser können keine Header setzen, dieser Weg ist daher für serverseitige Clients gedacht. Der Server ignoriert alles, was Sie senden; er liest nur mit, um das Schließen der Verbindung zu erkennen.

Jeder Frame ist ein JSON-Textframe {"type": <string>, "data": <payload>}:

{"type":"message","data":{"ID":90412,"isUser":false,"status":"generating","text":"Here are","...":"..."}}
{"type":"message","data":{"ID":90412,"isUser":false,"status":"generating","text":"Here are three options","...":"..."}}
{"type":"message","data":{"ID":90412,"isUser":false,"status":"finished","text":"Here are three options for ...","response_duration_ms":6210,"...":"..."}}
{"type":"ai_message_end"}

• Ihre eigenen Benutzernachrichten werden nicht an Ihre Verbindung zurückgespielt. Der Schlüssel handelt im Namen seines Inhabers, ein per Schlüssel gesteuerter Client sieht also nur KI-Nachrichten und Nachrichten anderer Personen.
• Solange kein Client verbunden ist, werden Events gepuffert, der nächsten Verbindung nachgeliefert und dann verworfen. Ein Client, der sich erst lange nach einer Runde verbindet, erhält daher womöglich zuerst veraltete Events daraus: Ignorieren Sie Nachrichten, deren ID Sie bereits in fertigem Zustand vorliegen haben.
• Streams liegen im Arbeitsspeicher des API-Servers. Wenn Sie verbunden sind, aber für eine Runde, die nachweislich läuft, nichts empfangen, weichen Sie auf Polling von GET /conversation/:id aus.

# 1. Start the turn without waiting
curl -X POST https://api.stickyprompts.com/api/v1/conversation/stream \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarise last week for the Northwind team.", "auto_model_type": "balanced" }'
# -> {"conversation_context_id":5120}

# 2. cURL cannot hold a WebSocket open; poll the newest messages instead
curl "https://api.stickyprompts.com/api/v1/conversation/5120?page=1&size=2" \
  -H "Authorization: Bearer $STICKY_API_KEY"

import asyncio, json, os, requests, websockets

KEY = os.environ["STICKY_API_KEY"]
BASE = "https://api.stickyprompts.com/api/v1"

start = requests.post(
    f"{BASE}/conversation/stream",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"message": "Summarise last week for the Northwind team.", "auto_model_type": "balanced"},
).json()
cid = start["conversation_context_id"]

async def listen():
    url = f"wss://api.stickyprompts.com/api/v1/conversation/{cid}/ws"
    async with websockets.connect(url, additional_headers={"Authorization": f"Bearer {KEY}"}) as ws:
        async for frame in ws:
            event = json.loads(frame)
            if event["type"] == "message" and not event["data"]["isUser"]:
                print(event["data"]["status"], len(event["data"]["text"]))
            elif event["type"] == "error_message":
                print("Failed:", event["data"]["error_text"], event["data"]["error_id"])
                break
            elif event["type"] == "ai_message_end":
                break

asyncio.run(listen())

import WebSocket from "ws"; // Node: browsers cannot send the Authorization header

const KEY = process.env.STICKY_API_KEY;
const BASE = "https://api.stickyprompts.com/api/v1";

const { conversation_context_id: cid } = await fetch(`${BASE}/conversation/stream`, {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Summarise last week for the Northwind team.", auto_model_type: "balanced" }),
}).then((r) => r.json());

const ws = new WebSocket(`wss://api.stickyprompts.com/api/v1/conversation/${cid}/ws`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
ws.on("message", (raw) => {
  const { type, data } = JSON.parse(raw);
  if (type === "message" && !data.isUser) console.log(data.status, data.text.length);
  if (type === "error_message") { console.error(data.error_text, data.error_id); ws.close(); }
  if (type === "ai_message_end") ws.close();
});

GET /conversation/:id/stream

Ein veralteter Endpunkt für Server-Sent Events. Verwenden Sie stattdessen den WebSocket oder Polling. Im aktuellen Code schreibt der Sendepfad für Unterhaltungen nur in den WebSocket. Dieser Stream liefert daher nur error_message- und run_data-Events für Fehler bei Prompt-Ausführungen und bleibt ansonsten offen, ohne Nachrichteninhalte zu senden.

Der Endpunkt gibt 404 {"error":"Stream not found"} zurück, wenn der Server für die Unterhaltung keinen Stream im Arbeitsspeicher hält. Andernfalls antwortet er mit Content-Type: text/event-stream und Frames der Form event:<name>\ndata:<json>\n\n, wobei <name> für message, error_message (Array aus {run_id, error_id, error_text, model_name}), run_data (Array aus RunHistory-Objekten) oder close (data: Stream closed) steht.

Unterhaltungen lesen

GET /conversation/:id

Gibt eine Unterhaltung mit einer Seite ihrer Nachrichten zurück, neueste zuerst. Die Paginierungsdaten stehen in den Response-Headern X-Total-Count (Gesamtzahl der Nachrichten), X-Page und X-Page-Size.

Zugriff. Der Inhaber; Benutzer, die per Freigabe chat_view oder chat_contribute haben; oder, wenn :id der öffentliche Slug einer geteilten Unterhaltung ist, jeder, den der Freigabetyp zulässt (public: alle, internal: alle angemeldeten Benutzer, workspace: Mitglieder des Workspace des Inhabers).

{
  "credits_used": "0.4213",
  "conversation_context_id": 5120,
  "conversation_context_name": "Q4 newsletter subject lines",
  "conversation_context_slug": "aB3dE5gH",
  "expensive_warning_threshold": 1000,
  "public_slug": null,
  "share_type": "",
  "is_public": false,
  "user_name": "John Smith",
  "messages": [
    { "ID": 90412, "isUser": false, "status": "finished", "text": "Here are three options ...", "...": "..." },
    { "ID": 90411, "isUser": true, "status": "finished", "text": "Draft three subject lines ...", "...": "..." }
  ],
  "next_message_ai_model_id": 12,
  "next_message_ai_model_style": "prompty",
  "next_message_auto_model_type": null,
  "next_message_reasoning_effort": null,
  "has_sub_conversations": false,
  "unsupported_files": null,
  "current_user_permission": "chat_contribute",
  "owner_id": 77,
  "user_count": 1,
  "team_shares": null,
  "agent_id": null,
  "invited_agents": [],
  "is_agent_chat": false
}

Fehler. 403 {"error":"You are not allowed to access this conversation"}, 404 {"error":"Conversation not found"}.

GET /conversation

Listet Ihre Chat-Unterhaltungen auf, die zuletzt aktiven zuerst. Aufgeführt werden nur interaktive Chat-Unterhaltungen mit mindestens einer Nachricht.

Antwort. 200 mit einem Array aus Unterhaltungsobjekten (leer: []). Bei jedem Objekt sind user und project vorgeladen, dazu kommen message_count, credits_used und in messages nur die letzte Nachricht (mit geleertem attachments). Beachten Sie die camelCase-Schlüssel publicSlug, isPublic, userId, projectId, runId, isInteractive und forkedFromConversationId neben den snake_case-Schlüsseln.

[
  {
    "ID": 5120, "CreatedAt": "2026-09-28T09:13:58Z", "UpdatedAt": "2026-09-28T09:14:10Z", "DeletedAt": null,
    "slug": "aB3dE5gH", "publicSlug": null, "isPublic": false, "share_type": "",
    "userId": 77, "user": { "ID": 77, "first_name": "John", "last_name": "Smith", "...": "..." },
    "next_message_ai_model_id": 12, "next_message_ai_style": "prompty",
    "next_message_auto_model_type": null, "next_message_reasoning_effort": null,
    "projectId": null, "project": null, "agent_id": null,
    "name": "Q4 newsletter subject lines", "source": "chat",
    "messages": [ { "ID": 90412, "isUser": false, "text": "Here are three options ...", "...": "..." } ],
    "isInteractive": true, "expensive_warning_threshold": 1000,
    "forkedFromConversationId": null,
    "message_count": 2, "credits_used": "0.4213"
  }
]

GET /conversation/:id/used_prompts

Gibt die gespeicherten Prompts zurück, die in dieser Unterhaltung ausgeführt wurden, jeden nur einmal und einschließlich der Vergleichs-Threads: ein Array aus { "id", "name", "slug", "ai_model_id", "user_id" } oder []. Die Reihenfolge ist nicht festgelegt.

Unterhaltungen verwalten

PATCH /conversation/:id

Benennt eine Unterhaltung um und schiebt sie an den Anfang der Liste. Nur für den Inhaber.

Antwort. 200 mit dem Unterhaltungsobjekt. Fehler. 403 {"error":"You are not allowed to edit this conversation"}.

PATCH /conversation/:id/model

Legt Modell, Stil und Denkaufwand für die nächsten Runden fest. Erlaubt für den Inhaber und für Benutzer mit chat_contribute. Sendet außerdem ein WebSocket-Event ai_model_change.

Antwort. 200 {"message":"Model changed successfully"}. Fehler. 400 {"error":"Cannot change model for agent conversations"}, 403, wenn Ihnen der Zugriff fehlt.

POST /conversation/:id/fork

Legt eine neue Unterhaltung mit dem Namen "Forked from <name>" an, die Kopien aller Nachrichten bis einschließlich message_id enthält. Anhänge, Tools und die Datensätze zu MCP-Genehmigungen werden mitkopiert, die Einstellungen für Modell, Stil und Denkaufwand bleiben erhalten. Die Quellunterhaltung muss Ihnen gehören oder geteilt sein, sonst erhalten Sie 403.

Antwort. 200 mit einer reduzierten Unterhaltungsantwort: conversation_context_id, conversation_context_name, conversation_context_slug, public_slug, is_public, user_name, messages (hier älteste zuerst) und credits_used: "0". Die übrigen Schlüssel haben Nullwerte.

DELETE /conversation/:id

Löscht die Unterhaltung und ihre Nachrichten per Soft Delete und blendet ihre Prompt-Ausführungen im Ausführungsverlauf aus. Nur für den Inhaber.

curl -X DELETE https://api.stickyprompts.com/api/v1/conversation/5120 \
  -H "Authorization: Bearer $STICKY_API_KEY"

Antwort. 200 {"message":"Conversation deleted successfully"}. Fehler. 404 {"error":"Conversation not found or you do not have permission to delete it"}.

POST /conversation/:id/retry

Führt die letzte Runde erneut aus, wenn die neueste KI-Nachricht mit einem Fehler geendet hat. Die fehlgeschlagene Nachricht wird an Ort und Stelle (gleiche ID) mit dem aktuellen Modell und Stil der Unterhaltung bzw. des Agenten neu generiert. Nur für den Inhaber. Kein Body.

Antwort. 200 mit:

• bei einer normalen Chat-Runde einer Message. Bei Modellen mit stream_support: true kehrt der Aufruf sofort mit der Nachricht im Zustand status: "thinking" zurück, und der Inhalt kommt über den WebSocket oder per Polling; bei anderen Modellen wird die fertige Nachricht zurückgegeben;
• bei einer Runde, die aus einem gespeicherten Prompt stammt, einem Array aus RunHistory-Objekten.

Fehler. 400 {"error":"Last AI message does not have an error"}, 400 {"error":"No user message found in this conversation"}, 403, 500 {"error":"..."}.

POST /conversation/:id/snooze-expensive-warning

Sobald die credits_used einer Unterhaltung ihren expensive_warning_threshold (Standard 1000) überschreiten, zeigt die Web-App eine Nutzungswarnung an. Dieser Aufruf verdoppelt den Schwellenwert so oft, bis er über der aktuellen Nutzung liegt. Nur für den Inhaber.

Antwort. 200 mit dem Unterhaltungsobjekt und seinem neuen expensive_warning_threshold. Fehler. 400, wenn die Nutzung noch unter dem Schwellenwert liegt.

POST /conversation/:id/agents

Lädt einen Ihrer Agenten in die Unterhaltung ein, damit er sich erwähnen lässt (@mentioned). Nur für den Inhaber; in Agenten-Chats nicht erlaubt (400).

Antwort. 200 {"message":"Agent invited successfully"}. Fehler. 404 {"error":"Agent not found or not owned by user"}, 403.

DELETE /conversation/:id/agents/:agentId

Entfernt einen eingeladenen Agenten. Nur für den Inhaber.

Antwort. 200 {"message":"Agent removed successfully"}. Fehler. 400 {"error":"Invalid agent ID"}, 404.

MCP-Tool-Genehmigungen

Dieser Ablauf greift, wenn eine Runde einen Remote-MCP-Server nutzt (ein remote_mcp-Tool oder einen Agenten mit MCP-Servern), dessen Konfiguration require_approval: true enthält, und das Modell über das OpenAI-Responses-Protokoll läuft, den einzigen Pfad, der Genehmigungen erzeugt. Workflow-Ausführungen genehmigen immer automatisch.

1. Das Modell möchte ein MCP-Tool aufrufen. Die Generierung hält an, und die KI-Nachricht erhält in mcp_approval_requests einen Eintrag pro angefordertem Aufruf. Beim Streaming-Pfad wird außerdem der Text Approval required for action: <name> samt Server-Label und Argumenten an den Nachrichtentext angehängt.
2. Jeder Eintrag verwendet Go-Feldnamen als Schlüssel (keine JSON-Tags). Approved: null bedeutet ausstehend, true oder false bedeutet entschieden.

{
  "ID": 311, "CreatedAt": "2026-09-28T09:20:01Z", "UpdatedAt": "2026-09-28T09:20:01Z", "DeletedAt": null,
  "ApprovalRequestID": "mcpr_abc123",
  "Approved": null,
  "ServerLabel": "crm",
  "Name": "create_contact",
  "Arguments": "{\"email\":\"jane@northwind.example\"}",
  "MCPToolID": 0,
  "MessageID": 90415
}

3. Entscheiden Sie mit POST /conversation/:id/approve und verwenden Sie dabei die numerische ID des Eintrags, nicht ApprovalRequestID.
4. Der Server speichert die Entscheidung und startet eine neue KI-Runde, die sie an das Modell weitergibt. Die Fortsetzung ist eine neue KI-Nachricht.

POST /conversation/:id/approve

Genehmigt einen ausstehenden MCP-Tool-Aufruf oder lehnt ihn ab.

Antwort. 200 mit dem JSON-String "Successfully handled approval", nicht mit einem Objekt. Die Fortsetzungsnachricht wird nicht zurückgegeben: Lesen Sie sie mit GET /conversation/:id oder über den WebSocket.

Fehler. 404 {"error":"Conversation not found"}, 404 {"error":"MCP Approval request not found"}, 400 {"error":"Approval request already processed"}, 400 {"error":"No messages in conversation"}, 500. Die Fortsetzung verwendet das fest eingestellte Modell für die nächste Nachricht; bei Unterhaltungen mit automatischer Modellwahl wird das nicht unterstützt.

Modellvergleich

Eine Sub-Conversation führt dieselbe Nachricht mit zwei oder mehr Modellen nebeneinander aus, mit einem „Thread“ pro Modell. Solange sie aktiv ist, gehen Folgenachrichten an die übergeordnete Unterhaltung an jeden Thread. Beim Schließen wählen Sie einen Gewinner-Thread, dessen Verlauf in der übergeordneten Unterhaltung weitergeht. Das ist die API-Seite von Modelle vergleichen.

POST /conversation/:id/sub-conversation

Startet einen Vergleich und wartet auf alle Threads.

Als Stil gilt der Stil der Unterhaltung, sonst Ihr bevorzugter Stil, sonst prompty.

Antwort. 200 mit der Hüllen-Message (type: "sub_conversation"). Deren sub_conversation enthält parent_conversation_context_id, threads, selected_thread_id und is_active: true. Jeder Thread hat ai_model_id, ai_model, thread_conversation_context_id, thread_conversation_context (mit messages), unsupported_files und credits_used.

Fehler. 400 bei weniger als 2 Modellen, 400 {"error":"AI model not found: <id>"}, 400 {"error":"An active sub-conversation already exists. Close it before creating a new one."}.

POST /conversation/:id/sub-conversation/stream

Die Streaming-Variante: gleiche Pfadparameter und gleicher Body, sie kehrt aber zurück, sobald die Benutzernachrichten existieren. Die Antworten der Threads streamen dann auf den WebSocket der übergeordneten Unterhaltung, und in der Antwort enthält messages bei jedem Thread nur die Benutzernachricht.

POST /sub-conversation/:id/close

Schließt einen aktiven Vergleich in einer Unterhaltung, die Ihnen gehört.

Antwort. 204 No Content. Fehler. 404, wenn der Vergleich nicht gefunden wird oder nicht aktiv ist.

POST /sub-conversation/:id/select-thread

Legt fest, welcher Thread mit seinen Nachrichten als Verlauf der Unterhaltung gilt. Die Sub-Conversation muss geschlossen sein; nur für den Inhaber.

Antwort. 204 No Content.

Teilen

Alle vier Freigabe-Endpunkte erwarten die numerische Unterhaltungs-ID und stehen nur dem Inhaber zur Verfügung (sonst 404 {"error":"Conversation not found"}).

POST /conversation/:id/share

Teilt die Unterhaltung per Link. Erzeugt einen 32-stelligen öffentlichen Slug, falls noch keiner existiert, und setzt isPublic: true. Die geteilte Unterhaltung lesen Sie mit GET /conversation/{public_slug}.

Antwort. 200 {"message":"Conversation shared successfully","publicSlug":"<32 chars>"}. Fehler. 400 {"error":"Invalid share type"}.

POST /conversation/:id/revoke-share

Setzt isPublic: false. Der Slug bleibt erhalten. Kein Body.

Antwort. 200 {"message":"Conversation share successfully revoked"}.

POST /conversation/:id/regenrate-share-slug

Ersetzt den öffentlichen Slug, sodass alte Links nicht mehr funktionieren. Der Pfad lautet tatsächlich regenrate, genau wie angegeben. Kein Body.

Antwort. 200 {"slug":"<new 32 chars>"}.

POST /conversation/:id/share-with-teams

Teilt die Unterhaltung schreibgeschützt mit Ihren Teams. Die Liste beschreibt den vollständigen Sollzustand für Ihre Teams: Jedes Team, dem Sie angehören und das nicht aufgeführt ist, verliert die Freigabe. Ausgenommen sind Teams, die bereits chat_contribute haben (etwa das Team, für das eine Team-Unterhaltung angelegt wurde). Stellt außerdem sicher, dass ein öffentlicher Slug existiert.

Antwort. 200 {"message":"Conversation shared successfully with teams","publicSlug":"<32 chars>"}. Fehler. 403 {"error":"You are not a member of team <name>"}, 404 bei unbekannten Teams.

Nachrichten

POST /message/:id/export

Exportiert eine einzelne Nachricht als DOCX- oder PDF-Datei, entweder als Download-Link oder direkt in eine verbundene Speicherintegration wie Google Drive. Dafür muss Ihnen die Unterhaltung gehören, oder Sie brauchen darauf mindestens chat_view.

Antwort. 200 mit genau einer der folgenden Formen:

{ "path": "https://<storage host>/<bucket>/<userId>/<random>.pdf" }

{ "entry": { "id": "...", "name": "Q4 subject lines.docx", "kind": "file", "mime_type": "...", "web_url": "...", "parent_id": "...", "...": "..." } }

Fehler. 400 {"error":"invalid format"}, 400 {"error":"invalid folder_id"}, 400 {"error":"unknown export target"}, 403 {"error":"you are not allowed to export this message"} oder ein Zielordner ohne Schreibrecht, 404, wenn die Nachricht nicht gefunden wird oder die Integration nicht verbunden ist, 409 {"error":"reconnect_required"}, 501, wenn der Anbieter keinen Upload unterstützt, 500.

Verwandte Seiten

• Prompts und Ausführungen - gespeicherte Prompts ausführen; jede Ausführung legt eine Unterhaltung an.
• Fehler, Paginierung und Kontingente - Fehlerformate, die 429-Gründe und Paginierungs-Header.
• Tool-Referenz - send_message, get_conversation, list_conversations, delete_conversation.