# Konverzace

> Výpis, počítání, čtení a mazání konverzací uživatele API klíče.

Konverzace je uložená historie chatu: zprávy vyměněné s modelem nebo
[asistentem](assistants.md), její název a několik vazeb (asistent, organizace, úkol,
běh workflow). Konverzace vytváří endpoint [chatu](chat.md); žá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](chat.md).

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í](account.md).

## Výpis konverzací

| | |
|---|---|
| Endpoint | `POST /api/v3/conversation/find` |
| Rozsah | `ayeto.conversation` |
| Limit požadavků | [default](conventions.md#limity-pozadavku) |

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í](conventions.md#filtry).
Pro všechno pošlete `{}`; samotné tělo je povinné.

| Pole | Typ | Povinné | Popis |
|---|---|---|---|
| `filters` | pole | Ne | Podmínky filtru, viz [filtry](conventions.md#filtry) a [příklady](#uzitecne-filtry) 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í](#pocet-konverzaci).

### Užitečné filtry

Filtry mohou používat jakékoli pole [konverzace](#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](conventions.md#filtry).

### Odpověď

`200 OK` s polem [konverzací](#konverzace).

### 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](conventions.md#chyby).

### 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](conventions.md#limity-pozadavku) |

Vrací počet konverzací uživatele, které odpovídají filtrům, viz
[počítání](conventions.md#pocitani).

### Požadavek

Stejný objekt dotazu jako u [výpisu konverzací](#vypis-konverzaci); 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
42
```

### 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](conventions.md#chyby).

### 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
7
```

## Čtení konverzace

| | |
|---|---|
| Endpoint | `POST /api/v3/conversation/get` |
| Rozsah | `ayeto.conversation` |
| Limit požadavků | [default](conventions.md#limity-pozadavku) |

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](conventions.md#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í](#konverzace).

### 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](#priklad).

## Smazání konverzace

| | |
|---|---|
| Endpoint | `POST /api/v3/conversation/delete` |
| Rozsah | `ayeto.conversation` |
| Limit požadavků | [default](conventions.md#limity-pozadavku) |

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](conventions.md#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](chat.md). |
| `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](models-and-tools.md)). 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](assistants.md), 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](workflows.md), 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](#zprava) | 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](conventions.md#spolecna-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ů](#volani-nastroju-v-obsahu-zpravy) 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](#priloha) | 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ů](#volani-nastroju-v-obsahu-zpravy). 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](chat.md)
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`.