Přehled endpointů | CODEXIS AI Agent

Reference všech volání Codexis AI agent API. Cesty jsou relativní k https://vm.codexis.ai a každé volání nese hlavičku X-Api-Key. Vytvoření klíče, chybové kódy a bezpečnostní zásady popisuje Integrace přes API.

Virtuální stroj

GET /api/v1/vm vrátí stav virtuálního počítače.
POST /api/v1/vm/start nastartuje virtuální počítač.
POST /api/v1/vm/stop vypne virtuální počítač.

Chat

POST /api/v1/chats pošle dotaz agentovi.
GET /api/v1/chats vypíše vaše konverzace.
GET /api/v1/chats/{chatId} vrátí konverzaci i s průběhem.
DELETE /api/v1/chats/{chatId} smaže konverzaci.
POST /api/v1/chats/{chatId}/stop zastaví rozepsanou odpověď.
GET /api/v1/chats/{chatId}/messages/{messageId} vyzvedne odpověď na dotaz.
GET /api/v1/chats/{chatId}/messages/{messageId}/events streamuje odpověď průběžně.
GET /api/v1/chats/{chatId}/events streamuje dění celé konverzace.
GET /api/v1/models vrátí dostupné modely a jejich volby.
GET /api/v1/jurisdictions vrátí dostupné právní řády.
GET /api/v1/skills vrátí vaše dovednosti.
GET /api/v1/agents vrátí vaše agenty.

Soubory

POST /api/v1/files nahraje soubor do pracovního prostoru agenta.
GET /api/v1/files/{path} stáhne soubor z pracovního prostoru.
DELETE /api/v1/files/{path} smaže soubor nebo složku z pracovního prostoru.
GET /api/v1/directories/{path} vypíše obsah složky.
POST /api/v1/directories/{path} založí složku v pracovním prostoru.

Virtuální počítač

Agent běží na virtuálním počítači, který je jen váš. Dotaz zpracuje, když je počítač ve stavu RUNNING.

GET `/api/v1/vm`

Vrátí stav virtuálního počítače, na kterém běží váš agent.

Parametry

Žádné.

Vrací

{ "status": "RUNNING" }

Stav je jedna z hodnot RUNNING, STOPPED, STARTING, STOPPING.

Příklad požadavku

curl -H "X-Api-Key: api-…" https://vm.codexis.ai/api/v1/vm

POST `/api/v1/vm/start`

Nastartuje virtuální počítač.

Parametry

Žádné.

Vrací

{ "status": "STARTING" }

Odpovědí je 202. Přechod do stavu RUNNING trvá desítky sekund, ověřte si ho voláním GET /api/v1/vm.

Příklad požadavku

curl -X POST -H "X-Api-Key: api-…" https://vm.codexis.ai/api/v1/vm/start

POST `/api/v1/vm/stop`

Vypne virtuální počítač.

Parametry

Žádné.

Vrací

{ "status": "STOPPING" }

Odpovědí je 202. Samotné vypnutí chvíli trvá.

Příklad požadavku

curl -X POST -H "X-Api-Key: api-…" https://vm.codexis.ai/api/v1/vm/stop

Číselníky

Hodnoty, které přijímá POST /api/v1/chats, si nemusíte pamatovat — API je umí vyjmenovat. Popisky ctí hlavičku Accept-Language (cs, en, sk); bez ní přijdou česky.

GET `/api/v1/models`

Vrátí jazykové modely, kterými může konverzace odpovídat, včetně voleb, které každý model přijímá.

Parametry

Žádné.

Vrací

[
  {
    "id": "GPT_5_6_TERRA",
    "label": "GPT-5.6 Terra",
    "description": "Vyvážená konfigurace GPT-5.6 mezi inteligencí a cenou.",
    "provider": "OPENAI",
    "status": "UP",
    "default": true,
    "deprecated": false,
    "settings": [
      {
        "key": "reasoningEffort",
        "label": "Úroveň uvažování",
        "options": [
          { "value": "LOW", "label": "Nízká" },
          { "value": "MEDIUM", "label": "Střední" },
          { "value": "HIGH", "label": "Vysoká" }
        ],
        "defaultValue": "MEDIUM"
      }
    ]
  }
]

id string. Hodnota pro pole model při posílání dotazu.
provider string. Jedna z hodnot OPENAI, ANTHROPIC, GOOGLE.
status string. Aktuální dostupnost poskytovatele: UP, DEGRADED, DOWN, UNKNOWN.
default boolean. Model použitý, když model v dotazu vynecháte.
deprecated boolean. Model je na odchodu; zůstává funkční, ale nevybírejte ho pro nové integrace.
settings pole objektů. Volby, které model přijímá. Vybrané hodnoty posíláte jako settings dotazu, key a options[].value přesně tak, jak tu stojí. Zastaralé modely žádné volby nenabízejí.

Příklad požadavku

curl -H "X-Api-Key: api-…" https://vm.codexis.ai/api/v1/models

GET `/api/v1/jurisdictions`

Vrátí právní řády, ve kterých agent umí hledat.

Parametry

Žádné.

Vrací

[
  { "id": "CZ", "label": "Česká republika" },
  { "id": "SK", "label": "Slovensko" }
]

Hodnotu id posíláte v poli jurisdictions dotazu.

Příklad požadavku

curl -H "X-Api-Key: api-…" https://vm.codexis.ai/api/v1/jurisdictions

GET `/api/v1/skills`

Vrátí dovednosti dostupné na vašem účtu, nejpoužívanější první.

Parametry

Žádné.

Vrací

[
  {
    "id": "8f2c9d41-5b7e-4a03-9c66-1d4e8b2a7f50",
    "name": "planner",
    "fullName": "demo-plugin:planner",
    "description": "Plánuje rešerši judikatury"
  }
]

V poli skillIds dotazu můžete použít id, name i fullName.

Příklad požadavku

curl -H "X-Api-Key: api-…" https://vm.codexis.ai/api/v1/skills

GET `/api/v1/agents`

Vrátí agenty dostupné na vašem účtu.

Parametry

Žádné.

Vrací

Stejný tvar jako u dovedností: id, name, fullName a description. V poli agentId dotazu můžete použít kteroukoli z prvních tří hodnot.

Příklad požadavku

curl -H "X-Api-Key: api-…" https://vm.codexis.ai/api/v1/agents

Soubory

POST `/api/v1/files`

Nahraje soubor do pracovního prostoru agenta, aby na něj šlo odkázat v dotazu.

Parametry

Tělo požadavku je multipart/form-data.

file soubor, povinné. Obsah nahrávaného souboru. Soubor musí mít název a nějaký obsah.
destination string, volitelné. Cílová složka v pracovním prostoru. Výchozí je složka pro nahrané soubory.
temporary boolean, volitelné. Odloží soubor stranou místo do zvolené složky. Výchozí: false. Nelze poslat spolu s destination, jinak přijde 400.

Vrací

{
  "name": "smlouva.pdf",
  "path": "/uploads/smlouva.pdf",
  "size": 284913
}

Odpovědí je 201. Hodnotu path předáváte v poli filePaths při posílání dotazu, size je velikost v bajtech.

Příklad požadavku

curl -X POST -H "X-Api-Key: api-…" \
  -F "file=@smlouva.pdf" \
  https://vm.codexis.ai/api/v1/files

Odkládací soubory

Posíláte-li dokument, který má agent jen jednorázově posoudit a nemá zůstat mezi vašimi soubory, přidejte temporary=true. Soubor se uloží do vlastní podsložky .tmp, takže opakované nahrání stejného názvu nic nepřepíše.

curl -X POST -H "X-Api-Key: api-…" \
  -F "file=@smlouva.pdf" \
  -F "temporary=true" \
  https://vm.codexis.ai/api/v1/files

Vrácenou cestu použijete v filePaths úplně stejně jako u běžného nahrání.

Odkládací soubory se samy nemažou

Složka .tmp nemá žádnou dobu platnosti a nic ji neuklízí. Až soubor přestanete potřebovat, smažte ho voláním DELETE /api/v1/files/{path}, jinak vám v pracovním prostoru zůstane napořád.

GET `/api/v1/files/{path}`

Stáhne soubor z pracovního prostoru. Obsah se streamuje, takže velikost souboru nehraje roli.

Parametry

path, povinné, v cestě. Cesta souboru tak, jak ji vrací nahrání (path) nebo výpis složky (entries[].path). Připojuje se za /api/v1/files i s lomítky, nic se nekóduje.

Vrací

Binární obsah souboru s jeho skutečným Content-Type, délkou v Content-Length a názvem v Content-Disposition (UTF-8, takže diakritika v názvech funguje).

404, na této cestě žádný soubor není.
400, cesta vede na složku.
403, cesta míří mimo váš pracovní prostor.

Příklad požadavku

curl -H "X-Api-Key: api-…" -o smlouva.pdf \
  https://vm.codexis.ai/api/v1/files/home/codexis/uploads/smlouva.pdf

GET `/api/v1/directories/{path}`

Vypíše obsah složky pracovního prostoru — jednu úroveň, bez skrytých souborů a bez obsahu souborů. Bez cesty (GET /api/v1/directories) vypíše domovskou složku.

Parametry

path, volitelné, v cestě. Cesta složky, připojená za /api/v1/directories i s lomítky. Výchozí je domovská složka.

Vrací

{
  "path": "/home/codexis/uploads",
  "entries": [
    {
      "name": "smlouva.pdf",
      "path": "/home/codexis/uploads/smlouva.pdf",
      "type": "FILE",
      "size": 284913,
      "modifiedTime": "2026-07-30T09:12:41Z",
      "mimeType": "application/pdf"
    }
  ],
  "totalEntries": 1
}

entries[].type string. Jedna z hodnot FILE, DIRECTORY, SYMLINK, OTHER.
entries[].path string. Cesta použitelná pro stažení, přiložení k dotazu i smazání.
Do podsložky se zanoříte dalším voláním s její cestou.

Příklad požadavku

curl -H "X-Api-Key: api-…" \
  https://vm.codexis.ai/api/v1/directories/home/codexis/uploads

DELETE `/api/v1/files/{path}`

Smaže soubor nebo složku z pracovního prostoru agenta.

Parametry

path, povinné, v cestě. Cesta mazaného souboru nebo složky, připojená za /api/v1/files i s lomítky. Berte ji z pole path odpovědi na nahrání nebo z výpisu složky.
recursive boolean, volitelné, v adrese. Povolí smazat i složku, ve které něco je. Výchozí: false.

Vrací

Odpovědí je 204 s prázdným tělem.

404, na této cestě nic není.
409, mažete složku, ve které něco je, a neposlali jste recursive=true.
403, cesta míří mimo váš pracovní prostor.

Příklad požadavku

curl -X DELETE -H "X-Api-Key: api-…" \
  https://vm.codexis.ai/api/v1/files/home/codexis/uploads/smlouva.pdf

Složku i s obsahem smažete takto:

curl -X DELETE -H "X-Api-Key: api-…" \
  "https://vm.codexis.ai/api/v1/files/home/codexis/davka-2026-07?recursive=true"

POST `/api/v1/directories/{path}`

Založí složku na zadané cestě. Hodí se, když si dávku dokumentů chcete nahrát do vlastní složky.

Parametry

path, povinné, v cestě. Cesta nové složky, připojená za /api/v1/directories i s lomítky. Nadřazená složka už musí existovat.

Vrací

{
  "name": "davka-2026-07",
  "path": "/home/codexis/davka-2026-07"
}

Odpovědí je 201. Vrácenou cestu můžete rovnou použít jako destination při nahrávání souborů.

409, složka na této cestě už existuje.
404, nadřazená složka neexistuje.
403, cesta míří mimo váš pracovní prostor.

Příklad požadavku

curl -X POST -H "X-Api-Key: api-…" \
  https://vm.codexis.ai/api/v1/directories/home/codexis/davka-2026-07

Konverzace

POST `/api/v1/chats`

Pošle dotaz agentovi, buď do nové konverzace, nebo do existující.

Parametry

Tělo požadavku je JSON.

input string, povinné. Text dotazu. Jediné pole, které musíte poslat.
chatId string, volitelné. UUID konverzace, do které se dotaz přidá. Výchozí je nová konverzace. Při pokračování se model, settings, jurisdictions a webSearchEnabled přebírají z konverzace.
agentId string, volitelné. Agent, který má odpovědět, zadaný svým ID, názvem nebo celým názvem. Nabídku vrací GET /api/v1/agents. Výchozí je váš výchozí agent.
skillIds pole řetězců, volitelné. Dovednosti, které má mít agent pro tento dotaz k dispozici, zadané svými ID, názvy nebo celými názvy. Nabídku vrací GET /api/v1/skills.
filePaths pole řetězců, volitelné. Cesty souborů z pracovního prostoru, které se k dotazu přiloží. Hodnoty berte z pole path v odpovědi na nahrání souboru.
model string, volitelné. Jazykový model, hodnota id z GET /api/v1/models, třeba GPT_5_6_TERRA nebo CLAUDE_SONNET_5. Výchozí je model označený v nabídce jako default. Neznámý model vrátí 400 se seznamem platných hodnot.
jurisdictions pole řetězců, volitelné. Právní řády, ve kterých má agent hledat, hodnoty id z GET /api/v1/jurisdictions.
webSearchEnabled boolean, volitelné. Povolí agentovi hledat i na internetu. Výchozí: false.
settings pole objektů, volitelné. Doladění modelu, stejné volby jako v aplikaci. Které volby model přijímá, říká pole settings v GET /api/v1/models.
- key string. Název volby.
- value string. Hodnota volby.

Vrací

{
  "id": "9c2e5b71-0f4d-4c8a-9a11-6b7e2f0d5c33",
  "chatId": "3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85",
  "status": "in_progress",
  "createdAt": "2026-07-30T09:14:22Z",
  "model": "GPT_5_6_SOL",
  "text": ""
}

Odpověď 202 přijde okamžitě, ještě než agent domyslí. Stihne-li agent odpovědět rovnou, přijde 201 se stavem completed.

id string. UUID odpovědi agenta. Spolu s chatId jím odpověď vyzvednete.
chatId string. UUID konverzace. Pošlete-li ho v dalším dotazu, konverzace pokračuje.
status string. Jedna z hodnot in_progress a completed. Se stavem completed je text odpovědi celý.
text string. Text odpovědi napsaný zatím.
model string. Jazykový model, kterým konverzace odpovídá.
createdAt string. Čas vzniku odpovědi ve formátu ISO 8601.
parts pole objektů. Z čeho se odpověď skládá, v pořadí, jak vznikala. Popisují je Části odpovědi.

Příklad požadavku

curl -X POST -H "X-Api-Key: api-…" \
  -H "Content-Type: application/json" \
  -d '{"input": "Zkontroluj výpovědní lhůty v přiložené smlouvě.", "filePaths": ["/uploads/smlouva.pdf"]}' \
  https://vm.codexis.ai/api/v1/chats

Pokračování v konverzaci

Chcete-li se doptat, pošlete další dotaz se stejným chatId. Agent zná celý předchozí průběh.

curl -X POST -H "X-Api-Key: api-…" \
  -H "Content-Type: application/json" \
  -d '{"chatId": "3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85", "input": "A co záruky?"}' \
  https://vm.codexis.ai/api/v1/chats

GET `/api/v1/chats`

Vypíše vaše konverzace, připnuté první a pak od nejnovější.

Parametry

offset číslo, volitelné, v adrese. Kolik konverzací přeskočit. Výchozí: 0.
limit číslo, volitelné, v adrese. Kolik konverzací vrátit, nejvýše 200. Výchozí: 50.

Vrací

{
  "chats": [
    {
      "chatId": "3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85",
      "title": "Výpovědní lhůty ve smlouvě",
      "status": "completed",
      "createdAt": "2026-07-30T09:14:22Z",
      "modifiedAt": "2026-07-30T09:16:03Z",
      "model": "GPT_5_6_TERRA",
      "pinned": false,
      "webSearchEnabled": false,
      "jurisdictions": ["CZ"]
    }
  ],
  "offset": 0,
  "limit": 50,
  "totalCount": 1
}

status je in_progress, dokud konverzace odpovídá, jinak completed.

Příklad požadavku

curl -H "X-Api-Key: api-…" "https://vm.codexis.ai/api/v1/chats?offset=0&limit=50"

GET `/api/v1/chats/{chatId}`

Vrátí konverzaci i s celým dosavadním průběhem.

Parametry

chatId string, povinné, v cestě. UUID konverzace.

Vrací

{
  "chat": { "chatId": "3f8b1a20-…", "title": "Výpovědní lhůty ve smlouvě", "status": "completed" },
  "messages": [
    { "id": "71d3…", "role": "USER", "status": "completed", "text": "Zkontroluj výpovědní lhůty…" },
    { "id": "9c2e…", "role": "ASSISTANT", "status": "completed", "text": "Výpovědní lhůty ve smlouvě…", "parts": [] }
  ]
}

chat objekt. Stejný souhrn jako ve výpisu konverzací.
messages pole objektů. Průběh v pořadí, jak vznikal. role je USER, nebo ASSISTANT; odpovědi agenta nesou i parts.

Příklad požadavku

curl -H "X-Api-Key: api-…" \
  https://vm.codexis.ai/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85

DELETE `/api/v1/chats/{chatId}`

Smaže konverzaci i s jejími odpověďmi. Probíhající odpověď se před smazáním zastaví.

Parametry

chatId string, povinné, v cestě. UUID konverzace.

Vrací

Odpovědí je 204 s prázdným tělem. Neexistující konverzace vrátí 404.

Příklad požadavku

curl -X DELETE -H "X-Api-Key: api-…" \
  https://vm.codexis.ai/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85

POST `/api/v1/chats/{chatId}/stop`

Zastaví odpověď, kterou konverzace právě píše. U konverzace, která nic nepíše, se nic nestane a vrátí se její aktuální stav.

Parametry

chatId string, povinné, v cestě. UUID konverzace.

Vrací

Odpovědí je 202 se souhrnem konverzace ve stejném tvaru jako ve výpisu. Zastavení může ještě chvíli dobíhat, takže status může být stále in_progress.

Příklad požadavku

curl -X POST -H "X-Api-Key: api-…" \
  https://vm.codexis.ai/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85/stop

GET `/api/v1/chats/{chatId}/messages/{messageId}`

Vyzvedne odpověď na dotaz.

Parametry

chatId string, povinné, v cestě. UUID konverzace, ze které odpověď je. Berte ho z pole chatId odpovědi na dotaz.
messageId string, povinné, v cestě. UUID odpovědi agenta. Berte ho z pole id odpovědi na dotaz.

Vrací

{
  "id": "9c2e5b71-0f4d-4c8a-9a11-6b7e2f0d5c33",
  "chatId": "3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85",
  "status": "completed",
  "createdAt": "2026-07-30T09:14:22Z",
  "model": "GPT_5_6_SOL",
  "text": "Výpovědní lhůty ve smlouvě jsou nastavené takto…"
}

Stejný objekt jako POST /api/v1/chats, s textem dopsaným podle stavu. Odpověď se píše postupně, proto se na ni chodíte dívat opakovaně, rozumný interval je pět až deset sekund. K vyzvednutí zůstává, dokud konverzace existuje.

Příklad požadavku

curl -H "X-Api-Key: api-…" \
  https://vm.codexis.ai/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85/messages/9c2e5b71-0f4d-4c8a-9a11-6b7e2f0d5c33

GET `/api/v1/chats/{chatId}/messages/{messageId}/events`

Streamuje jednu odpověď průběžně přes Server-Sent Events, místo opakovaného vyzvedávání.

Parametry

chatId string, povinné, v cestě. UUID konverzace.
messageId string, povinné, v cestě. UUID odpovědi agenta.

Vrací

Proud text/event-stream. Každá událost message nese aktuální podobu odpovědi ve stejném tvaru jako POST /api/v1/chats; poslední událost se jmenuje completed a stream jí končí.

event: message
data: {"id":"9c2e5b71-…","chatId":"3f8b1a20-…","status":"in_progress","text":"Výpovědní lhůty"}

event: completed
data: {"id":"9c2e5b71-…","chatId":"3f8b1a20-…","status":"completed","text":"Výpovědní lhůty ve smlouvě jsou nastavené takto…"}

Příklad požadavku

curl -N -H "X-Api-Key: api-…" \
  https://vm.codexis.ai/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85/messages/9c2e5b71-0f4d-4c8a-9a11-6b7e2f0d5c33/events

GET `/api/v1/chats/{chatId}/events`

Streamuje dění celé konverzace přes Server-Sent Events. Zůstává otevřený i mezi dotazy, hodí se pro integraci, která konverzaci sleduje dlouhodobě.

Parametry

chatId string, povinné, v cestě. UUID konverzace.

Vrací

Proud text/event-stream ve stejném tvaru jako u streamu jedné odpovědi: událost message pro každou změnu poslední odpovědi v konverzaci a completed, jakmile je hotová.

Příklad požadavku

curl -N -H "X-Api-Key: api-…" \
  https://vm.codexis.ai/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85/events

Části odpovědi

Pole parts popisuje, z čeho se odpověď skládá, v pořadí, jak vznikala. Zatímco text je hotový text, parts ukazují i cestu k němu: co si agent nastudoval, co spustil a odkud čerpal. Potřebujete-li jen odpověď, vystačíte si s text a parts můžete ignorovat.

{
  "partId": "b1f0c4d2-77a5-4e3b-9c81-2d5f6a0e4b19",
  "type": "TEXT",
  "content": "<p>Výpovědní lhůta je <a href=\"https://next.codexis.cz/doc/CR26785_2026_01_01\">tříměsíční</a>…</p>",
  "citations": [
    {
      "citationId": "c1",
      "source": { "type": "URL", "url": "https://next.codexis.cz/doc/CR26785_2026_01_01" }
    }
  ]
}

Každá část má partId (UUID) a type. Podle typu se liší, která další pole nesou obsah:

TEXT — kus odpovědi. content je HTML a citace už má vsazené uvnitř jako odkazy na zdroj. Tytéž zdroje najdete rozepsané v citations.
REASONING — úvaha agenta, také jako HTML v content.
TOOL — agent spustil nástroj. toolName říká který, toolCallId je identifikátor spuštění a state jeho stav.
WEB_SEARCH — hledání na internetu. query je hledaný dotaz, sources nalezené zdroje. Jako toolName přijde web_search.
SKILL — agent použil dovednost.
AGENT — odpověď zpracoval jiný agent.
FILE — do odpovědi vstoupil soubor z pracovního prostoru.

Další pole:

state string. Stav u částí, které něco spouštějí. Jedna z hodnot PENDING, COMPLETE, ERROR.
citations pole objektů. Citace v této části. Každá má citationId a source.
sources pole objektů. Zdroje, se kterými část pracovala. Každý má type (URL nebo FILE) a podle něj url, nebo path.

Části přibývají postupně

Dokud je odpověď ve stavu in_progress, parts se dopisují a jejich obsah se mění. Ustálí se ve chvíli, kdy odpověď přejde do stavu completed.

OpenAPI specifikace

Strojově čitelné schéma celého API najdete v openapi.yaml. Načtete ho do Postmanu, Insomnie nebo generátoru klientů.

Jak zacházet s klíčem a co znamenají chybové kódy, popisuje Integrace přes API.