← Back to Blog
Tutorial · 10 min read

API v3: Jak pracovat s konverzacemi programaticky

AYETO Team ·
API v3: Jak pracovat s konverzacemi programaticky

Základní informace

Vlastnost Hodnota
Base URL /api/v3/conversation
Autentizace API Key s scope ayeto.conversation
Rate Limit Default limits

🔐 Autentizace

API Key

Všechny endpointy vyžadují API klíč s oprávněním (scope) ayeto.conversation.

Hlavička pro autentizaci

uni-api-key: <YOUR_API_KEY>

Formát API klíče

API klíč má následující formát:

ayeto-{64_random_hex_characters}

Příklad:

ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Scopes

Pro použití conversation endpointů musí mít API klíč scope: - ayeto.conversation - specifický scope pro konverzace - * - wildcard scope (přístup ke všem endpointům)

Chybové odpovědi autentizace

Chyba Popis
API key not provided Hlavička uni-api-key chybí nebo je prázdná.
API key is invalid API klíč neexistuje, je deaktivován, nebo nemá požadovaný scope.

📋 Dostupné Endpointy

Endpoint Metoda Popis
/api/v3/conversation/find POST Vyhledání konverzací
/api/v3/conversation/get POST Získání jedné konverzace
/api/v3/conversation/delete POST Smazání konverzace

📤 Response Model - PublicConversationView

Všechny endpointy vracejí konverzace v tomto formátu:

Pole Typ Popis
id UUID Unikátní identifikátor konverzace.
name string Název konverzace.
model string ID použitého LLM modelu.
img_gen_model string ID modelu pro generování obrázků.
summary string Shrnutí konverzace (pokud bylo vygenerováno).
organization_id UUID \| null ID organizace (pokud je konverzace v kontextu organizace).
assistant_id UUID \| null ID asistenta (pokud byl použit).
messages BasicLLMMessageView[] Seznam zpráv v konverzaci.
created ModelMeta Metadata o vytvoření.
updated ModelMeta Metadata o poslední aktualizaci.
accessed ModelMeta Metadata o posledním přístupu.

Message Model - BasicLLMMessageView

Pole Typ Popis
id UUID Unikátní identifikátor zprávy.
timestamp integer Unix timestamp vytvoření zprávy (v milisekundách).
role string Role zprávy: system, user, assistant, tool, internal.
content string \| null Textový obsah zprávy.
reasoning_content string \| null Reasoning obsah (pokud model podporuje).
model string \| null ID použitého modelu pro tuto zprávu.
img_gen ImgGenMessage \| null Data vygenerovaného obrázku.

ModelMeta

Pole Typ Popis
user_id UUID \| null ID uživatele, který provedl akci.
timestamp integer Unix timestamp akce (v milisekundách).

🔍 POST /api/v3/conversation/find

Vyhledání konverzací s možností filtrování, řazení a stránkování.

Request Body - DbParams

Parametry se předávají jako JSON v těle požadavku:

Parametr Typ Povinné Popis
sort_key string Ne Pole pro řazení (např. updated.timestamp, name).
sort_order integer Ne Směr řazení: 0 = ASC, 1 = DESC.
limit_from integer Ne Počáteční index pro stránkování.
limit_to integer Ne Koncový index pro stránkování.
filters array Ne Pole filtrů.

Filtry

Filtry se předávají jako pole s podmínkami:

["field", "operator", "value"]

Podporované operátory

Operátor Popis
== Rovná se
!= Nerovná se
< Menší než
> Větší než
<= Menší nebo rovno
>= Větší nebo rovno
regex Regulární výraz

Příklady filtrů

["name", "regex", ".*test.*"]
["model", "==", "gpt-4o"]
["updated.timestamp", ">", 1735815581000]
["assistant_id", "==", "123e4567-e89b-12d3-a456-426614174000"]

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Moje konverzace",
    "model": "gpt-4o",
    "img_gen_model": "dall-e-3",
    "summary": "Diskuze o programování v Pythonu...",
    "organization_id": null,
    "assistant_id": null,
    "messages": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "timestamp": 1735815581000,
        "role": "user",
        "content": "Ahoj, jak napíšu funkci v Pythonu?",
        "reasoning_content": null,
        "model": null,
        "img_gen": null
      },
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "timestamp": 1735815582000,
        "role": "assistant",
        "content": "Funkci v Pythonu definujete pomocí klíčového slova `def`...",
        "reasoning_content": null,
        "model": "gpt-4o",
        "img_gen": null
      }
    ],
    "created": {
      "user_id": "880e8400-e29b-41d4-a716-446655440003",
      "timestamp": 1735815580000
    },
    "updated": {
      "user_id": "880e8400-e29b-41d4-a716-446655440003",
      "timestamp": 1735815582000
    },
    "accessed": {
      "user_id": null,
      "timestamp": 0
    }
  }
]

📖 POST /api/v3/conversation/get

Získání jedné konverzace podle ID.

Query Parameters

Parametr Typ Povinné Popis
entity_id UUID Ano ID konverzace.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Moje konverzace",
  "model": "gpt-4o",
  "img_gen_model": "dall-e-3",
  "summary": "",
  "organization_id": null,
  "assistant_id": null,
  "messages": [...],
  "created": {...},
  "updated": {...},
  "accessed": {...}
}

🗑️ POST /api/v3/conversation/delete

Smazání konverzace podle ID.

Query Parameters

Parametr Typ Povinné Popis
entity_id UUID Ano ID konverzace ke smazání.

Response

Vrací UUID smazané konverzace:

"550e8400-e29b-41d4-a716-446655440000"

🔧 cURL Příklady

1. Získání všech konverzací

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{}'

2. Získání konverzací s řazením (nejnovější první)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_key": "updated.timestamp",
    "sort_order": 1
  }'

3. Získání konverzací se stránkováním (prvních 10)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_key": "updated.timestamp",
    "sort_order": 1,
    "limit_from": 0,
    "limit_to": 10
  }'

4. Získání konverzací s filtrem (podle modelu)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["model", "==", "gpt-4o"]]
  }'

5. Získání konverzací s filtrem (podle názvu - regex)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["name", "regex", ".*Python.*"]]
  }'

6. Získání konverzací pro konkrétního asistenta

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["assistant_id", "==", "123e4567-e89b-12d3-a456-426614174000"]]
  }'

7. Získání konverzací novějších než určité datum

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["created.timestamp", ">", 1735689600000]]
  }'

8. Kombinace více filtrů

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_key": "updated.timestamp",
    "sort_order": 1,
    "limit_from": 0,
    "limit_to": 20,
    "filters": [
      ["model", "==", "gpt-4o"],
      ["created.timestamp", ">", 1735689600000]
    ]
  }'

9. Získání jedné konverzace podle ID

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/get?entity_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

10. Smazání konverzace

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/delete?entity_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

11. Verbose curl pro debugging

curl -v -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "limit_from": 0,
    "limit_to": 5
  }'

⚠️ Chybové stavy

HTTP Status Popis
400 Chybný request (nevalidní parametry, špatný formát filtru).
401 Neplatný nebo chybějící API klíč (uni-api-key hlavička).
403 Nedostatečná oprávnění (uživatel nemá přístup ke konverzaci).
404 Konverzace nenalezena.
500 Interní chyba serveru.

Příklad chybové odpovědi

{
  "detail": "not found, id: 550e8400-e29b-41d4-a716-446655440000"
}

🔄 Poznámky

  1. Oprávnění: Uživatel vidí pouze své vlastní konverzace (konverzace, které vytvořil).
  2. Filtry: Více filtrů v poli se aplikuje jako AND podmínka.
  3. Stránkování: Pro velké množství konverzací doporučujeme používat limit_from a limit_to.
  4. Řazení: Výchozí řazení není definováno, doporučujeme explicitně specifikovat sort_key a sort_order.
  5. Timestamp: Všechny timestampy jsou v milisekundách (Unix epoch * 1000).
#api #doc #ayeto #programming