Konverzace je uložená historie chatu: zprávy vyměněné s modelem nebo asistentem, její název a několik vazeb (asistent, organizace, úkol, běh workflow). Konverzace vytváří endpoint chatu; žádný endpoint pro jejich přímé vytvoření nebo úpravu neexistuje. Chcete-li v konverzaci pokračovat, pošlete její id jako conversation_id do chatu.

Všechny čtyři endpointy vidí jen konverzace uživatele API klíče:

konverzace, které uživatel zahájil v aplikaci nebo přes API, při osobním používání i v kterékoli organizaci, do které patří;
konverzace zahájené jeho jménem naplánovanými úkoly a běhy workflow.

Konverzace jiných uživatelů se nikdy nevracejí, ani když patří do stejné organizace nebo jsou veřejně sdíleny odkazem. Konverzace, která existuje, ale není vaše, se hlásí jako nenalezená.

Náklady konverzace jsou k dispozici z endpointu nákladů na využití.

Výpis konverzací


Endpoint	`POST /api/v3/conversation/find`
Rozsah	`ayeto.conversation`
Limit požadavků	default

Vrací konverzace uživatele, které odpovídají filtrům, od nejnovějších, pokud neřadíte jinak. Každá konverzace se vrací s celou historií zpráv, proto výsledky vždy stránkujte.

Požadavek

Tělo je objekt dotazu s obvyklými poli pro filtry, řazení a stránkování. Pro všechno pošlete {}; samotné tělo je povinné.

Pole	Typ	Povinné	Popis
`filters`	pole	Ne	Podmínky filtru, viz filtry a příklady níže. Více podmínek se kombinuje pomocí AND.
`sort_key`	řetězec	Ne	Pole, podle kterého se řadí, například `created.timestamp`, `updated.timestamp`, `accessed.timestamp` nebo `name`. Výchozí: `created.timestamp`, sestupně.
`sort_order`	celé číslo	Ne	`0` vzestupně, `1` sestupně. Výchozí `0`, když je nastaveno `sort_key`.
`limit_from`	celé číslo	Ne	Index prvního výsledku (od nuly). Bez něj se vrátí všechny odpovídající konverzace.
`limit_to`	celé číslo	Ne	Index za posledním výsledkem (výlučně), ne velikost stránky: `limit_from: 20, limit_to: 40` vrátí výsledky na pozicích 20 až 39 (počítáno od 0).

Chcete-li přečíst všechno, žádejte o stránky, dokud nepřijde stránka kratší, než jste požadovali. Celkový počet pro stránkovač získáte z počtu konverzací.

Užitečné filtry

Filtry mohou používat jakékoli pole konverzace, včetně polí zpráv (messages.content, messages.role, messages.model). Podmínky na zprávy se kontrolují proti každé uložené zprávě, včetně výsledků nástrojů a dalších zpráv, které se v messages nevracejí.

Cíl	Filtr
Konverzace s jedním asistentem	`["assistant_id", "==", "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90"]`
Jen osobní konverzace (bez organizace)	`["organization_id", "==", null]`
Konverzace v jedné organizaci	`["organization_id", "==", "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]`
Konverzace, které jste vedli sami, bez běhů úkolů a workflow	`["task_id", "==", null]`, `["task_execution_id", "==", null]`, `["workflow_run_id", "==", null]`
Konverzace vytvořené jedním workflow	`["workflow_id", "==", "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a"]`
Změněné od určitého okamžiku (ms od epochy)	`["updated.timestamp", ">=", 1759363200000]`
Název obsahuje slovo (bez ohledu na velikost písmen)	`["name", "regex", "invoice"]`
Některá zpráva obsahuje frázi (bez ohledu na velikost písmen)	`["messages.content", "regex", "delivery date"]`
Zahájené s jedním z několika modelů	`["model", "in", ["gpt-5", "claude-sonnet-4-5"]]`
Některou odpověď napsal daný model	`["messages.model", "==", "gpt-5"]`

Textové filtry se porovnávají s uloženým textem až poté, co API escapuje <, >, " a ', takže hodnota filtru obsahující tyto znaky odpovídá jen zřídka; viz filtry.

Odpověď

200 OK s polem konverzací.

Chyby

Stav	`detail`	Příčina
`403`	`permission denied`	Účet uživatele nemá povoleno číst konverzace.
`422`	chyba validace	Chybí tělo, nebo je neplatný filtr či `sort_key`.

Chyby autentizace, limitů požadavků a serveru jsou popsány v konvencích.

Příklad

20 naposledy změněných konverzací s jedním asistentem:

bash

curl -X POST "https://ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["assistant_id", "==", "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90"]],
    "sort_key": "updated.timestamp",
    "sort_order": 1,
    "limit_from": 0,
    "limit_to": 20
  }'

json

[
  {
    "id": "8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
    "name": "Delivery terms for order 1042",
    "model": "gpt-5",
    "summary": "",
    "organization_id": null,
    "assistant_id": "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90",
    "task_id": null,
    "task_execution_id": null,
    "workflow_id": null,
    "workflow_run_id": null,
    "public_sharing": false,
    "messages": [
      {
        "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "timestamp": 1759395601000,
        "role": "user",
        "content": "What delivery date did we agree for order 1042?",
        "reasoning_content": null,
        "model": null,
        "attachments": [],
        "tool_runs": {}
      },
      {
        "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e",
        "timestamp": 1759395606000,
        "role": "assistant",
        "content": "The agreed delivery date for order 1042 is 14 October 2026.",
        "reasoning_content": null,
        "model": "gpt-5",
        "attachments": [],
        "tool_runs": {}
      }
    ],
    "created": {"timestamp": 1759395600000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"},
    "updated": {"timestamp": 1759395606000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"},
    "accessed": {"timestamp": 1759395606000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"}
  }
]

Počet konverzací


Endpoint	`POST /api/v3/conversation/count`
Rozsah	`ayeto.conversation`
Limit požadavků	default

Vrací počet konverzací uživatele, které odpovídají filtrům, viz počítání.

Požadavek

Stejný objekt dotazu jako u výpisu konverzací; pro spočítání všech pošlete {}. Použije se jen filters: limit_from, limit_to a pole pro řazení se ignorují, takže můžete poslat stejné tělo jako pro zobrazovanou stránku.

Odpověď

200 OK s počtem odpovídajících konverzací jako celým číslem JSON.

json

Chyby

Stav	`detail`	Příčina
`403`	`permission denied`	Účet uživatele nemá povoleno číst konverzace.
`422`	chyba validace	Chybí tělo, nebo je neplatný filtr či `sort_key`.

Chyby autentizace, limitů požadavků a serveru jsou popsány v konvencích.

Příklad

Konverzace s jedním asistentem změněné od určitého okamžiku:

bash

curl -X POST "https://ayeto.ai/api/v3/conversation/count" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      ["assistant_id", "==", "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90"],
      ["updated.timestamp", ">=", 1759363200000]
    ]
  }'

json

Čtení konverzace


Endpoint	`POST /api/v3/conversation/get`
Rozsah	`ayeto.conversation`
Limit požadavků	default

Vrací jednu konverzaci s celou historií zpráv.

Požadavek

Pole	Typ	Povinné	Popis
`id`	UUID	Ano	Id konverzace.

Id lze místo toho poslat i jako parametr dotazu entity_id, bez těla nebo s {}; viz parametry.

Čtení konverzace se počítá jako její otevření: aktualizuje se její časové razítko accessed (nejvýše jednou za minutu).

Odpověď

200 OK s konverzací.

Chyby

Stav	`detail`	Příčina
`403`	`permission denied`	Účet uživatele nemá povoleno číst konverzace.
`404`	`entity not found, id: <id>`	Konverzace s tímto id neexistuje.
`404`	`entity not found`	Konverzace existuje, ale patří jinému uživateli.
`422`	chyba validace	Id chybí nebo není UUID, nebo se `id` a `entity_id` liší.

Příklad

bash

curl -X POST "https://ayeto.ai/api/v3/conversation/get" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b"}'

Odpovědí je jeden objekt ve stejném tvaru jako jedna položka příkladu výpisu.

Smazání konverzace


Endpoint	`POST /api/v3/conversation/delete`
Rozsah	`ayeto.conversation`
Limit požadavků	default

Trvale smaže konverzaci spolu se soubory, které k ní patří (přílohy v ní odeslané a obrázky či jiné soubory v ní vygenerované). Tuto akci nelze vrátit.

Požadavek

Pole	Typ	Povinné	Popis
`id`	UUID	Ano	Id konverzace.

Id lze místo toho poslat i jako parametr dotazu entity_id, bez těla nebo s {}; viz parametry.

Odpověď

200 OK s id smazané konverzace jako řetězcem JSON.

json

"8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b"

Chyby

Stav	`detail`	Příčina
`403`	`permission denied`	Účet uživatele nemá povoleno mazat konverzace.
`404`	`entity not found, id: <id>`	Konverzace s tímto id neexistuje.
`404`	`entity not found`	Konverzace existuje, ale patří jinému uživateli.
`422`	chyba validace	Id chybí nebo není UUID, nebo se `id` a `entity_id` liší.
`500`	`can not delete entity`	Konverzaci se nepodařilo smazat; zkuste to později.

Příklad

bash

curl -X POST "https://ayeto.ai/api/v3/conversation/delete" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b"}'

Konverzace

Objekt, který vracejí všechny endpointy konverzací.

Pole	Typ	Povinné	Popis
`id`	UUID	Ano	Id konverzace. Stejná hodnota je `conversation_id` chatu.
`name`	řetězec	Ano	Zobrazovaný název. `New conversation`, dokud se po první odpovědi nenavrhne název nebo dokud ho nenastavíte v aplikaci.
`model`	řetězec	Ano	Id modelu, se kterým byla konverzace zahájena (viz modely). Jednotlivé odpovědi mohou pocházet z jiného modelu; viz `model` zprávy.
`summary`	řetězec	Ano	Shrnutí vygenerované v aplikaci na vyžádání; prázdný řetězec, když žádné vygenerováno nebylo.
`organization_id`	UUID nebo null	Ne	Organizace, do které konverzace patří; `null` při osobním používání.
`assistant_id`	UUID nebo null	Ne	Asistent, se kterým se konverzace vede; `null` při chatu přímo s modelem.
`task_id`	UUID nebo null	Ne	Naplánovaný úkol, který konverzaci vytvořil.
`task_execution_id`	UUID nebo null	Ne	Běh tohoto úkolu.
`workflow_id`	UUID nebo null	Ne	Workflow, jehož krok s asistentem konverzaci vytvořil.
`workflow_run_id`	UUID nebo null	Ne	Běh tohoto workflow.
`public_sharing`	boolean	Ano	`true`, když uživatel konverzaci v aplikaci veřejně sdílel odkazem.
`messages`	pole Zpráv	Ano	Zprávy uživatele a asistenta v chronologickém pořadí. Systémové zprávy, zprávy nástrojů a další interní zprávy jsou vynechány.
`created`, `updated`, `accessed`	objekt	Ano	Metadata `{timestamp, user_id}`, viz společná pole. `updated` se mění s každou novou zprávou; `accessed` je okamžik, kdy byla konverzace naposledy otevřena.

Zpráva

Pole	Typ	Povinné	Popis
`id`	UUID	Ano	Id zprávy.
`timestamp`	časové razítko	Ano	Kdy zpráva vznikla (ms od epochy).
`role`	řetězec	Ano	`user` nebo `assistant`.
`content`	řetězec nebo null	Ne	Text zprávy v Markdownu. Ve zprávách asistenta obsahuje i volání nástrojů provedená během odpovídání.
`reasoning_content`	řetězec nebo null	Ne	Text uvažování modelu, pokud ho model vrací.
`model`	řetězec nebo null	Ne	Model, který napsal zprávu asistenta; u zpráv uživatele `null`.
`attachments`	pole Příloh	Ano	Soubory přiložené ke zprávě.
`tool_runs`	objekt	Ano	Odpovědi sub-asistentů volaných během této zprávy, viz volání nástrojů. Obvykle prázdné.

Příloha

Pole	Typ	Povinné	Popis
`filename`	řetězec	Ano	Název souboru.
`content_type`	řetězec	Ano	Typ MIME, například `image/png` nebo `application/pdf`.
`file_url`	řetězec	Ano	Veřejná URL souboru. Soubory odeslané nebo vygenerované v konverzaci se mažou spolu s ní.
`name`	řetězec nebo null	Ne	Zobrazovaný název, pokud se liší od `filename`.
`description`	řetězec nebo null	Ne	Krátký popis souboru.

Volání nástrojů v obsahu zprávy

Každý nástroj, který model zavolal při psaní zprávy asistenta, se v content objeví jako blok, který začíná "\n\n### calling AI tool ...\n" a končí "\n***\n". Text mezi oběma značkami je výstup nástroje zobrazený uživateli:

json

{
  "role": "assistant",
  "content": "Let me look that up.\n\n### calling AI tool ...\nSearching the web for \"order 1042 delivery\"...\n***\nThe agreed delivery date is 14 October 2026."
}

Pokud potřebujete jen text odpovědi, tyto bloky odstraňte. (Endpoint chatu je může ze své vlastní odpovědi vynechat pomocí remove_tool_calls; uložená konverzace je vždy zachovává.)

Když asistent zavolá jiného asistenta jako nástroj, odpověď tohoto asistenta se uloží do tool_runs pod klíčem, kterým je pozice volání nástroje v content zapsaná jako řetězec ("0" pro první volání nástroje, "1" pro druhé a tak dále). Každá hodnota má řetězec content ve stejném formátu a vlastní vnořené tool_runs.

Výpis konverzací #

Požadavek #

Užitečné filtry #

Odpověď #

Chyby #

Příklad #

Počet konverzací #

Požadavek #

Odpověď #

Chyby #

Příklad #

Čtení konverzace #

Požadavek #

Odpověď #

Chyby #

Příklad #

Smazání konverzace #

Požadavek #

Odpověď #

Chyby #

Příklad #

Konverzace #

Zpráva #

Příloha #

Volání nástrojů v obsahu zprávy #

Výpis konverzací

Požadavek

Užitečné filtry

Odpověď

Chyby

Příklad

Počet konverzací

Požadavek

Odpověď

Chyby

Příklad

Čtení konverzace

Požadavek

Odpověď

Chyby

Příklad

Smazání konverzace

Požadavek

Odpověď

Chyby

Příklad

Konverzace

Zpráva

Příloha

Volání nástrojů v obsahu zprávy