Přehled endpointů | CODEXIS AI Agent

Reference všech volání Codexis AI agent API. Cesty jsou relativní k adrese vaší instance 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.

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č.
POST /api/v1/files nahraje soubor do pracovního prostoru agenta.
POST /api/v1/chats pošle dotaz agentovi.
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.

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://<vaše-instance>/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://<vaše-instance>/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://<vaše-instance>/api/v1/vm/stop

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.

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://<vaše-instance>/api/v1/files

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, fields, 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. 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.
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. Jedna z hodnot GPT_5_6_SOL (GPT-5.6 Sol), GPT_5_6_TERRA (GPT-5.6 Terra), GPT_5_6_LUNA (GPT-5.6 Luna), GPT_5_5 (GPT-5.5), GPT_5_4 (GPT-5.4), GPT_5_4_MINI (GPT-5.4 mini), GPT_5_4_NANO (GPT-5.4 nano). Výchozí je model vaší instance.
jurisdictions pole řetězců, volitelné. Právní řády, ve kterých má agent hledat. Hodnoty CZ, SK, EU, AT, NL, FR.
webSearchEnabled boolean, volitelné. Povolí agentovi hledat i na internetu. Výchozí: false.
fields pole objektů, volitelné. Doladění modelu, stejné volby jako v aplikaci.
- 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.

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://<vaše-instance>/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://<vaše-instance>/api/v1/chats

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://<vaše-instance>/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://<vaše-instance>/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://<vaše-instance>/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85/events

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.