Beszélgetések és üzenetek

A beszélgetés egy chatszál: ugyanaz, amit a csapatod az alkalmazás Chat History részében lát. Egy üzenettel indítod, a modell válaszol, te pedig további üzeneteket küldesz. Az itt leírt kérések mind az API-kulcs tulajdonosának nevében futnak, ugyanazokkal a hozzáférésekkel, kvótákkal és munkaterületi szabályokkal, mintha ő maga dolgozna a böngészőben.

Minden útvonal a https://api.stickyprompts.com/api/v1 címhez képest értendő. A kérések törzse JSON. A fájlokat előbb a fájlvégpontokon keresztül töltöd fel, utána pedig az azonosítójukkal hivatkozol rájuk.

Így működik a chat

1. Indítsd el a beszélgetést a POST /conversation hívással (ez megvárja a teljes választ) vagy a POST /conversation/stream hívással (ez azonnal visszatér, a válasz pedig WebSocketen érkezik). Mindkettő egyetlen hívásban hozza létre a beszélgetést és küldi el az első üzenetet.
2. Folytasd a beszélgetést a POST /conversation/:id vagy a POST /conversation/:id/stream hívással.
3. Módosítsd a modellt, a stílust vagy a gondolkodási szintet a későbbi körökre a PATCH /conversation/:id/model hívással. A folytató kérések törzsében nem adhatsz meg modellt: a beszélgetés megjegyzi a „következő üzenet” beállításait.
4. Olvasd ki az előzményeket a GET /conversation/:id hívással (lapozható, a legújabb üzenet áll elöl), a beszélgetéseket pedig a GET /conversation hívással listázhatod.
5. Kövesd élőben a haladást a GET /conversation/:id/ws WebSocketen, vagy kérdezd le rendszeresen a GET /conversation/:id végpontot, és figyeld az AI-üzenet status mezőjét.

Azonosítók. A legtöbb végpont :id helyén a beszélgetés numerikus azonosítóját és a 8 karakteres slug értékét is elfogadja. A megosztási végpontok, a törlés, a jóváhagyás, valamint a WebSocket- és az SSE-stream csak a numerikus azonosítót fogadja el; ezeket lent mindenhol külön jelezzük.

A Message-objektum

Ezt adják vissza a nem streamelő küldési végpontok, ez szerepel a GET /conversation/:id válaszában, és ez a WebSocket message eseményeinek data tartalma.

{
  "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": []
}

Állapot. A thinking azt jelenti, hogy az AI-üzenet sora már létezik, de még semmi nem generálódott; a generating azt, hogy folyamatosan érkezik a részleges kimenet; a finished azt, hogy kész. A sikertelen AI-üzenet is finished állapotú, kitöltött error_text és error_id mezővel, ezért ne csak a status mezőt ellenőrizd, hanem ezeket is. A felhasználói üzenetek mindig finished állapotúak.

Kreditek. Minden credits_used mező JSON-stringként szerializált decimális szám, például "0.4213".

Üzenetek küldése

A kérés törzse

A POST /conversation és a POST /conversation/stream az összes alábbi mezőt elfogadja. A folytató végpontok csak a „folytatáskor is” jelölésű mezőket fogadják el, a többit szó nélkül figyelmen kívül hagyják. A kérés-feldolgozó (binder) egyetlen mezőt sem tesz szigorúan kötelezővé, de mindig küldj message mezőt és modellt.

Modellválasztás. Az auto_model_type az első, utána az ai_model_id következik, végül a projekt alapértelmezett modellje (X-Project-ID esetén). Ha egyik sem érvényes, a beszélgetés ugyan létrejön, de a küldés 503 {"error":"no AI model is selected, try reselecting model"} hibával elbukik, ezért indításkor mindig adj meg modellt vagy automatikus típust. Szó szerinti "auto" modellazonosító nincs. Ügynökchatben és @agent említéskor az ügynök modellje fut (prompty stílussal, gondolkodási szint nélkül). A modellnek meg kell felelnie a munkaterületed modellhozzáférési szabályainak és adatrezidencia-szabályainak, különben a küldés 503-as hibával elbukik.

Eszközök

Minden elem { "name": ..., "use": true | false } alakú. A nevek: web_search, image_generation, video_generation, speech_generation, music_generation, remote_mcp.

• Egy eszköz csak akkor jut el a modellhez, ha a modell tools képességei között szerepel. Ellenkező esetben a rendszer szó nélkül figyelmen kívül hagyja.
• A remote_mcp mellé "mcp_tool_id": <id> is kell: az egyik beállított távoli MCP-szervered azonosítója. Szerverenként egy elemet adj meg.
• Automatikus eszközválasztás. Az eszközöket támogató modelleknél egy kis osztályozó az üzenet alapján bekapcsolhatja a web_search és az image_generation eszközt (valamint a kódfuttatást), akkor is, ha nem kérted. Ha egy eszközhöz küldesz elemet, akár {"name":"web_search","use":false} formában, az osztályozó azt már nem adja hozzá. A kódfuttatásról kizárólag az osztályozó dönt.

POST /conversation

Létrehoz egy beszélgetést, elküldi az első üzenetet, és megvárja a teljes AI-választ, az esetleges eszközhívásokkal együtt. A válasz a kész AI-üzenet (Message); az új beszélgetés azonosítója ennek conversation_context_id mezője. Az első üzenetváltás után a beszélgetés automatikusan nevet kap. A fenti kéréstörzset fogadja, valamint az opcionális X-Project-ID headert.

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);

Válasz. 200, a törzsben az AI-üzenettel (lásd: A Message-objektum). Ha az AI-nak nem kell válaszolnia (több tagú csapatbeszélgetésben, @ai vagy ügynökemlítés nélkül), a válasz helyette 200 {"conversation_context_id": 5120}.

Hibák

Ha a szolgáltató generálás közben hibázik, a rendszer az AI-üzenetet akkor is elmenti az error_text és az error_id mezővel, és a POST /conversation/:id/retry hívással újrafuttathatod.

POST /conversation/stream

Ugyanazokat a headereket és ugyanazt a törzset fogadja, mint a POST /conversation, de már akkor visszatér, amikor a felhasználói üzenet eltárolódott. A generálás a háttérben folytatódik, a válasz pedig a WebSocketen érkezik, vagy pollinggal kérdezheted le.

{ "conversation_context_id": 5120 }

A felhasználói üzenet eltárolása előtt észlelt hibák (429-es kvótahiba, érvénytelen ügynök, nincs kiválasztott modell, korlátozott modell, érzékenyadat-blokkolás) továbbra is szinkron módon, a fentivel azonos formában érkeznek. A 200 utáni hibákról (modell- vagy eszközválasztás, tudásbázis-lekérés, szolgáltatói hiba) csak egy WebSocket error_message esemény értesít, és a rendszer egy AI-üzeneten rögzíti őket az error_text és az error_id mezővel.

A válasz fogadása

• WebSocket (ajánlott). Csatlakozz a GET /conversation/{conversation_context_id}/ws végponthoz. A csatlakozásod előtt kibocsátott eseményeket a szerver puffereli, és az első kliensnek visszajátssza, így ha közvetlenül a 200 után csatlakozol, semmiről nem maradsz le.
• Polling. Hívd meg a GET /conversation/:id?page=1&size=2 végpontot, és olvasd ki a legújabb AI-üzenetet (isUser: false; ez áll a lista elején, mert a sorrend a legújabbtól halad). Az AI-üzenet status: "thinking" állapottal jön létre, és a rendszer minden beérkező darab után elmenti, így előbb generating állapotot látsz egyre hosszabb text mezővel, majd finished állapotot. A finished állapotnál állj le, és ellenőrizd az error_id mezőt. Közvetlenül a 200 után előfordulhat, hogy az AI-üzenet még nem létezik: ha a legújabb üzenet még a sajátod, a generálás még nem indult el.

Valós idejű streamelés csak a stream_support: true beállítású modelleknél van. A többi modellnél a válasz egy darabban jelenik meg, amikor elkészül.

POST /conversation/:id

Elküld egy további üzenetet, és megvárja az AI válaszát. A modellt, a stílust és a gondolkodási szintet a beszélgetés next_message_* beállításai adják; ezeket előbb a PATCH /conversation/:id/model hívással módosíthatod.

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." }'

Válasz. Ugyanaz, mint a POST /conversation esetén: 200 az AI-üzenettel, vagy 200 {"conversation_context_id": ...}, ha az AI nem válaszol. Ha a beszélgetésben aktív modell-összehasonlítás fut, az üzenet párhuzamosan minden szálba eljut, és a válasz AI-üzenetek JSON-tömbje, szálanként egy elemmel.

Hibák. Ugyanazok, mint a POST /conversation esetén, továbbá 404 {"error":"Conversation not found"}. Üzenetet csak a tulajdonos, illetve a chat_contribute jogú felhasználók és csapatok küldhetnek; mindenki más 503 {"error":"you are not allowed to send messages in this conversation"} választ kap.

POST /conversation/:id/stream

Ugyanaz, mint a POST /conversation/:id, de azonnal 200 {"conversation_context_id": <id>} választ ad. A haladást WebSocketen vagy pollinggal követheted, ahogy a POST /conversation/stream esetén. Aktív modell-összehasonlításnál minden szál a szülőbeszélgetés WebSocketjére streamel.

Mikor válaszol az AI?

Az AI akkor válaszol egy üzenetre, ha az alábbiak közül bármelyik teljesül:

• csak egy felhasználónak van írási (contribute) hozzáférése a beszélgetéshez (ez a szokásos eset, ide tartozik minden API-kulccsal, team_id nélkül létrehozott beszélgetés);
• @ai szerepel a szövegben (kis- és nagybetűérzékeny);
• ügynökchatről van szó;
• a szöveg megemlíti (@mentions) egy, a beszélgetésbe meghívott ügynök címkéjét.

Különben az üzenet egyszerű felhasználói üzenetként tárolódik, amelyet a többi résztvevő is lát, a végpont pedig modellhívás nélkül 200 {"conversation_context_id": <id>} választ ad, a nem streamelő végpontokon is.

Ügynökök a beszélgetésben

• Ha létrehozáskor megadod az agent_id mezőt, ügynökchat jön létre. Ennek a modellje később nem módosítható.
• Egyfelhasználós beszélgetésben az @tag az adott kört a saját, ilyen címkéjű ügynöködhöz vagy egy veled megosztott ügynökhöz irányítja (címkeütközésnél a saját ügynökeid élveznek elsőbbséget). Többfelhasználós beszélgetésben csak az invited_agent_ids mezővel vagy a POST /conversation/:id/agents hívással meghívott ügynököket lehet megemlíteni.
• A válaszoló ügynököt az AI-üzenet rögzíti (agent_id, agent).

Streamelés

GET /conversation/:id/ws

WebSocket, amely a beszélgetés minden frissítését továbbítja. Csatlakozz a wss://api.stickyprompts.com/api/v1/conversation/5120/ws címhez, és az upgrade kérésben küldd el az Authorization: Bearer STICKY-API-... headert. A böngészők WebSocket objektumai nem tudnak headert beállítani, ezért ez a végpont szerveroldali klienseknek szól. A szerver figyelmen kívül hagy mindent, amit küldesz; csak a kapcsolat bezárását figyeli.

Minden frame JSON-t tartalmazó szöveges frame, {"type": <string>, "data": <payload>} alakban:

{"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"}

• A saját felhasználói üzeneteidet a kapcsolatod nem kapja vissza. A kulcs a tulajdonosa nevében jár el, így egy kulccsal működő kliens csak az AI-üzeneteket és a többi ember üzeneteit látja.
• Amíg egy kliens sem csatlakozik, a szerver puffereli az eseményeket, a következő kapcsolatnak visszajátssza, majd törli őket. Ha egy kliens jóval egy kör után csatlakozik, előbb elavult eseményeket kaphat abból a körből: hagyd figyelmen kívül azokat az üzeneteket, amelyeknek az ID értékét már befejezett állapotban tárolod.
• A streamek az API-szerver memóriájában élnek. Ha csatlakozol, de egy biztosan futó körről semmit nem kapsz, térj át a GET /conversation/:id rendszeres lekérdezésére.

# 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

Régi (legacy) Server-Sent Events végpont. Helyette a WebSocketet vagy a pollingot használd. A jelenlegi kódban a beszélgetések küldési útvonala csak a WebSocketre ír, így ez a stream csak a promptfuttatási hibák error_message és run_data eseményeit továbbítja, egyébként nyitva marad, de üzenettartalmat nem küld.

404 {"error":"Stream not found"} választ ad, ha a szerver memóriájában nincs stream a beszélgetéshez. Egyébként Content-Type: text/event-stream típussal válaszol, event:<name>\ndata:<json>\n\n alakú frame-ekkel, ahol a <name> értéke message, error_message ({run_id, error_id, error_text, model_name} elemek tömbje), run_data (RunHistory-objektumok tömbje) vagy close (data: Stream closed).

Beszélgetések olvasása

GET /conversation/:id

Egy beszélgetést ad vissza az üzeneteinek egy oldalával, a legújabbal kezdve. A lapozási metaadatok az X-Total-Count (az üzenetek teljes száma), az X-Page és az X-Page-Size válaszheaderben vannak.

Hozzáférés. A tulajdonos; a megosztás révén chat_view vagy chat_contribute joggal rendelkező felhasználók; illetve ha az :id helyén egy megosztott beszélgetés nyilvános slugja áll, mindenki, akit a megosztás típusa enged (public: bárki, internal: bármely bejelentkezett felhasználó, workspace: a tulajdonos munkaterületének tagjai).

{
  "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
}

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

GET /conversation

Listázza a chatbeszélgetéseidet, a legutóbb aktívval kezdve. Csak az interaktív, legalább egy üzenetet tartalmazó chatbeszélgetések szerepelnek benne.

Válasz. 200, beszélgetésobjektumok tömbjével (ha nincs találat: []). Mindegyikben előre be van töltve a user és a project, szerepel bennük a message_count és a credits_used, a messages tömbben pedig csak a legutóbbi üzenet (kiürített attachments mezővel). Figyelj: a snake_case kulcsok mellett camelCase kulcsok is vannak: publicSlug, isPublic, userId, projectId, runId, isInteractive és forkedFromConversationId.

[
  {
    "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

Visszaadja a beszélgetésben (az összehasonlító szálakat is beleértve) futtatott mentett promptokat, ismétlődés nélkül: { "id", "name", "slug", "ai_model_id", "user_id" } elemek tömbjét, vagy [] értéket. A sorrend nincs meghatározva.

Beszélgetések kezelése

PATCH /conversation/:id

Átnevez egy beszélgetést, és a lista elejére helyezi. Csak a tulajdonos hívhatja.

Válasz. 200, a beszélgetésobjektummal. Hibák. 403 {"error":"You are not allowed to edit this conversation"}.

PATCH /conversation/:id/model

Beállítja a következő körök modelljét, stílusát és gondolkodási szintjét. A tulajdonos és a chat_contribute jogú felhasználók hívhatják. Emellett egy ai_model_change WebSocket-eseményt is szétküld.

Válasz. 200 {"message":"Model changed successfully"}. Hibák. 400 {"error":"Cannot change model for agent conversations"}, illetve 403, ha nincs hozzáférésed.

POST /conversation/:id/fork

Új beszélgetést hoz létre "Forked from <name>" néven, és belemásol minden üzenetet a message_id azonosítójú üzenetig bezárólag. A mellékletek, az eszközök és az MCP-jóváhagyási rekordok is átmásolódnak, a modell-, stílus- és gondolkodásiszint-beállítások pedig megmaradnak. A forrásbeszélgetésnek a tiédnek vagy megosztottnak kell lennie, különben 403 a válasz.

Válasz. 200, egy szűkített beszélgetésválasszal: conversation_context_id, conversation_context_name, conversation_context_slug, public_slug, is_public, user_name, messages (itt a legrégebbivel kezdve) és credits_used: "0". A többi kulcs üres, alapértelmezett nullértéket tartalmaz.

DELETE /conversation/:id

Logikailag törli (soft delete) a beszélgetést és az üzeneteit, a promptfuttatásait pedig elrejti a futtatási előzmények közül. Csak a tulajdonos hívhatja.

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

Válasz. 200 {"message":"Conversation deleted successfully"}. Hibák. 404 {"error":"Conversation not found or you do not have permission to delete it"}.

POST /conversation/:id/retry

Újrafuttatja az utolsó kört, ha a legutóbbi AI-üzenet hibával zárult. A sikertelen üzenet helyben generálódik újra (ugyanazzal az ID értékkel), a beszélgetés aktuális modelljével és stílusával, ügynökchatnél pedig az ügynökével. Csak a tulajdonos hívhatja. Nincs kéréstörzs.

Válasz. 200, a törzsben:

• egyszerű chatkörnél egy Message-objektum. A stream_support: true beállítású modelleknél a hívás azonnal visszatér egy status: "thinking" állapotú üzenettel, a tartalom pedig WebSocketen vagy pollinggal érkezik; más modelleknél a kész üzenetet kapod vissza;
• mentett promptból indult körnél RunHistory-objektumok tömbje.

Hibák. 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

Ha egy beszélgetés credits_used értéke túllépi az expensive_warning_threshold küszöböt (alapértéke 1000), a webalkalmazás felhasználási figyelmeztetést jelenít meg. Ez a végpont addig duplázza a küszöböt, amíg az a jelenlegi felhasználás fölé nem kerül. Csak a tulajdonos hívhatja.

Válasz. 200, a beszélgetésobjektummal és az új expensive_warning_threshold értékkel. Hibák. 400, ha a felhasználás még a küszöb alatt van.

POST /conversation/:id/agents

Meghívja az egyik ügynöködet a beszélgetésbe, hogy meg lehessen említeni (@mentioned). Csak a tulajdonos hívhatja; ügynökchatekben nem engedélyezett (400).

Válasz. 200 {"message":"Agent invited successfully"}. Hibák. 404 {"error":"Agent not found or not owned by user"}, 403.

DELETE /conversation/:id/agents/:agentId

Eltávolít egy meghívott ügynököt. Csak a tulajdonos hívhatja.

Válasz. 200 {"message":"Agent removed successfully"}. Hibák. 400 {"error":"Invalid agent ID"}, 404.

MCP-eszközhívások jóváhagyása

Ez akkor érvényes, ha egy kör olyan távoli MCP-szervert használ (remote_mcp eszközzel, vagy MCP-szerverekkel rendelkező ügynökön keresztül), amelynek a konfigurációjában require_approval: true szerepel, és a modell az OpenAI Responses protokollon fut - jóváhagyási kérések csak ezen az útvonalon keletkeznek. Munkafolyamat-futtatásoknál a jóváhagyás mindig automatikus.

1. A modell egy MCP-eszköz meghívását kéri. A generálás leáll, és az AI-üzenet mcp_approval_requests mezőjébe minden kért hívásról bekerül egy elem. Streamelésnél az üzenet szövegéhez az Approval required for action: <name> szöveg is hozzáfűződik, a szervercímkével és az argumentumokkal együtt.
2. Az elemek kulcsai Go-mezőnevek (JSON-tagek nélkül). Az Approved: null függőben lévő kérést jelent, a true vagy a false eldöntöttet.

{
  "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. Dönts a POST /conversation/:id/approve hívással, az elem numerikus ID értékét használva, nem az ApprovalRequestID mezőt.
4. A szerver rögzíti a döntést, és új AI-kört indít, amely visszaadja azt a modellnek. A folytatás egy új AI-üzenet.

POST /conversation/:id/approve

Jóváhagy vagy elutasít egy függőben lévő MCP-eszközhívást.

Válasz. 200, a törzsben a "Successfully handled approval" JSON-string, nem objektum. A folytató üzenetet a végpont nem adja vissza: olvasd ki a GET /conversation/:id hívással vagy a WebSocketről.

Hibák. 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. A folytatás a beszélgetés rögzített, következő üzenetre beállított modelljét használja; automatikus modellválasztású beszélgetésben ez nem támogatott.

Modell-összehasonlítás

Az albeszélgetés (sub-conversation) ugyanazt az üzenetet két vagy több modellen futtatja egymás mellett, modellenként egy-egy „szálban”. Amíg aktív, a szülőbeszélgetésbe küldött további üzenetek minden szálba eljutnak. Lezárásakor kiválasztasz egy nyertes szálat, amelynek az előzményei a szülőben folytatódnak. Ez a Modellek összehasonlítása funkció API-oldala.

POST /conversation/:id/sub-conversation

Elindít egy összehasonlítást, és megvárja az összes szálat.

A stílus a beszélgetés stílusa; ha az nincs, a preferált stílusod; ha az sincs, akkor prompty.

Válasz. 200, a burkoló Message-objektummal (type: "sub_conversation"). Ennek sub_conversation mezője tartalmazza a parent_conversation_context_id, a threads, a selected_thread_id és az is_active: true értéket. Minden szálban szerepel az ai_model_id, az ai_model, a thread_conversation_context_id, a thread_conversation_context (messages tömbbel), az unsupported_files és a credits_used.

Hibák. 400, ha 2-nél kevesebb modellt adsz meg, 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

A streamelő változat: ugyanazok az útvonal-paraméterek és ugyanaz a törzs, de már akkor visszatér, amikor a felhasználói üzenetek létrejöttek. A szálak válaszai ezután a szülőbeszélgetés WebSocketjére streamelődnek, a válaszban pedig minden szál messages tömbje csak a felhasználói üzenetet tartalmazza.

POST /sub-conversation/:id/close

Lezár egy aktív összehasonlítást egy saját beszélgetésedben.

Válasz. 204 No Content. Hibák. 404, ha nem található, vagy nem aktív.

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

Módosítja, hogy melyik szál üzenetei számítanak a beszélgetés előzményeinek. Az albeszélgetésnek lezártnak kell lennie; csak a tulajdonos hívhatja.

Válasz. 204 No Content.

Megosztás

Mind a négy megosztási végpont a beszélgetés numerikus azonosítóját várja, és csak a tulajdonos hívhatja őket (különben 404 {"error":"Conversation not found"} a válasz).

POST /conversation/:id/share

Linkkel osztja meg a beszélgetést. Ha még nincs, 32 karakteres nyilvános slugot generál, és beállítja az isPublic: true értéket. A megosztott beszélgetést a GET /conversation/{public_slug} hívással olvashatod ki.

Válasz. 200 {"message":"Conversation shared successfully","publicSlug":"<32 chars>"}. Hibák. 400 {"error":"Invalid share type"}.

POST /conversation/:id/revoke-share

Beállítja az isPublic: false értéket. A slug megmarad. Nincs kéréstörzs.

Válasz. 200 {"message":"Conversation share successfully revoked"}.

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

Lecseréli a nyilvános slugot, így a régi linkek nem működnek tovább. Az útvonalban regenrate áll, pontosan így írva. Nincs kéréstörzs.

Válasz. 200 {"slug":"<new 32 chars>"}.

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

Csak olvasásra megosztja a beszélgetést a csapataiddal. A lista a csapataidra vonatkozó teljes kívánt állapot: a megosztás megszűnik minden olyan csapatodnál, amely nem szerepel benne, kivéve azokat, amelyeknek már chat_contribute joguk van (például azt a csapatot, amelyhez a csapatbeszélgetés létrejött). A végpont arról is gondoskodik, hogy legyen nyilvános slug.

Válasz. 200 {"message":"Conversation shared successfully with teams","publicSlug":"<32 chars>"}. Hibák. 403 {"error":"You are not a member of team <name>"}, illetve 404 ismeretlen csapatoknál.

Üzenetek

POST /message/:id/export

Egyetlen üzenetet exportál DOCX- vagy PDF-fájlba, letöltési linkként vagy közvetlenül egy csatlakoztatott tárhelyintegrációba, például a Google Drive-ba. A beszélgetésnek a tiédnek kell lennie, vagy legalább chat_view joggal kell rendelkezned hozzá.

Válasz. 200, pontosan az egyikkel az alábbiak közül:

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

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

Hibák. 400 {"error":"invalid format"}, 400 {"error":"invalid folder_id"}, 400 {"error":"unknown export target"}, 403 {"error":"you are not allowed to export this message"}, vagy 403, ha a célmappa nem írható, 404, ha az üzenet nem található, vagy az integráció nincs csatlakoztatva, 409 {"error":"reconnect_required"}, 501, ha a szolgáltató nem tud feltölteni, valamint 500.

Kapcsolódó oldalak

• Promptok és futtatások - mentett promptok futtatása; minden futtatás létrehoz egy beszélgetést.
• Hibák, lapozás és kvóták - hibaformátumok, a 429-es válaszok reason értékei és a lapozási headerek.
• Eszközreferencia - a megfelelő MCP-eszközök: send_message, get_conversation, list_conversations, delete_conversation.