Prehľad endpointov | CODEXIS AI Agent

Referencia všetkých volaní Codexis AI agent API. Cesty sú relatívne k adrese vašej instancie a každé volanie nesie hlavičku X-Api-Key. Vytvorenie kľúča, chybové kódy a bezpečnostné zásady popisuje Integrácia cez API.

GET /api/v1/vm vráti stav virtuálneho počítača.
POST /api/v1/vm/start naštartuje virtuálny počítač.
POST /api/v1/vm/stop vypne virtuálny počítač.
POST /api/v1/files nahrá súbor do pracovného priestoru agenta.
POST /api/v1/chats pošle otázku agentovi.
GET /api/v1/chats/{chatId}/messages/{messageId} vyzdvihne odpoveď na otázku.
GET /api/v1/chats/{chatId}/messages/{messageId}/events streamuje odpoveď priebežne.
GET /api/v1/chats/{chatId}/events streamuje dianie celej konverzácie.

Virtuálny počítač

Agent beží na virtuálnom počítači, ktorý je len váš. Otázku spracuje, keď je počítač v stave RUNNING.

GET `/api/v1/vm`

Vráti stav virtuálneho počítača, na ktorom beží váš agent.

Parametre

Žiadne.

Vracia

{ "status": "RUNNING" }

Stav je jedna z hodnôt RUNNING, STOPPED, STARTING, STOPPING.

Príklad požiadavky

curl -H "X-Api-Key: api-…" https://<vaša-instancia>/api/v1/vm

POST `/api/v1/vm/start`

Naštartuje virtuálny počítač.

Parametre

Žiadne.

Vracia

{ "status": "STARTING" }

Odpoveďou je 202. Prechod do stavu RUNNING trvá desiatky sekúnd, overte si ho volaním GET /api/v1/vm.

Príklad požiadavky

curl -X POST -H "X-Api-Key: api-…" https://<vaša-instancia>/api/v1/vm/start

POST `/api/v1/vm/stop`

Vypne virtuálny počítač.

Parametre

Žiadne.

Vracia

{ "status": "STOPPING" }

Odpoveďou je 202. Samotné vypnutie chvíľu trvá.

Príklad požiadavky

curl -X POST -H "X-Api-Key: api-…" https://<vaša-instancia>/api/v1/vm/stop

Súbory

POST `/api/v1/files`

Nahrá súbor do pracovného priestoru agenta, aby sa naň dalo v otázke odkázať.

Parametre

Telo požiadavky je multipart/form-data.

file súbor, povinné. Obsah nahrávaného súboru. Súbor musí mať názov a nejaký obsah.
destination string, voliteľné. Cieľová zložka v pracovnom priestore. Východisková je zložka pre nahrané súbory.

Vracia

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

Odpoveďou je 201. Hodnotu path predávate v poli filePaths pri posielaní otázky, size je veľkosť v bajtoch.

Príklad požiadavky

curl -X POST -H "X-Api-Key: api-…" \
  -F "file=@zmluva.pdf" \
  https://<vaša-instancia>/api/v1/files

Konverzácie

POST `/api/v1/chats`

Pošle otázku agentovi, buď do novej konverzácie, alebo do existujúcej.

Parametre

Telo požiadavky je JSON.

input string, povinné. Text otázky. Jediné pole, ktoré musíte poslať.
chatId string, voliteľné. UUID konverzácie, do ktorej sa otázka pridá. Východisková je nová konverzácia. Pri pokračovaní sa model, fields, jurisdictions a webSearchEnabled preberajú z konverzácie.
agentId string, voliteľné. Agent, ktorý má odpovedať, zadaný svojím ID, názvom alebo celým názvom. Východiskový je váš východiskový agent.
skillIds pole reťazcov, voliteľné. Schopnosti, ktoré má mať agent pre túto otázku k dispozícii, zadané svojimi ID, názvami alebo celými názvami.
filePaths pole reťazcov, voliteľné. Cesty súborov z pracovného priestoru, ktoré sa k otázke priložia. Hodnoty berte z poľa path v odpovedi na nahranie súboru.
model string, voliteľné. Jazykový model. Jedna z hodnôt 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ýchodiskový je model vašej instancie.
jurisdictions pole reťazcov, voliteľné. Právne poriadky, v ktorých má agent hľadať. Hodnoty CZ, SK, EU, AT, NL, FR.
webSearchEnabled boolean, voliteľné. Povolí agentovi hľadať aj na internete. Východisková hodnota: false.
fields pole objektov, voliteľné. Doladenie modelu, rovnaké voľby ako v aplikácii.
- key string. Názov voľby.
- value string. Hodnota voľby.

Vracia

{
  "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": ""
}

Odpoveď 202 príde okamžite, ešte než agent domyslí. Ak agent stihne odpovedať rovno, príde 201 so stavom completed.

id string. UUID odpovede agenta. Spolu s chatId ním odpoveď vyzdvihnete.
chatId string. UUID konverzácie. Ak ho pošlete v ďalšej otázke, konverzácia pokračuje.
status string. Jedna z hodnôt in_progress a completed. So stavom completed je text odpovede celý.
text string. Text odpovede napísaný doteraz.
model string. Jazykový model, ktorým konverzácia odpovedá.
createdAt string. Čas vzniku odpovede vo formáte ISO 8601.

Príklad požiadavky

curl -X POST -H "X-Api-Key: api-…" \
  -H "Content-Type: application/json" \
  -d '{"input": "Skontroluj výpovedné lehoty v priloženej zmluve.", "filePaths": ["/uploads/zmluva.pdf"]}' \
  https://<vaša-instancia>/api/v1/chats

Pokračovanie v konverzácii

Ak sa chcete dopytovať ďalej, pošlite ďalšiu otázku s rovnakým chatId. Agent pozná celý predchádzajúci priebeh.

curl -X POST -H "X-Api-Key: api-…" \
  -H "Content-Type: application/json" \
  -d '{"chatId": "3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85", "input": "A čo záruky?"}' \
  https://<vaša-instancia>/api/v1/chats

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

Vyzdvihne odpoveď na otázku.

Parametre

chatId string, povinné, v ceste. UUID konverzácie, z ktorej odpoveď je. Berte ho z poľa chatId odpovede na otázku.
messageId string, povinné, v ceste. UUID odpovede agenta. Berte ho z poľa id odpovede na otázku.

Vracia

{
  "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ýpovedné lehoty v zmluve sú nastavené takto…"
}

Rovnaký objekt ako POST /api/v1/chats, s textom dopísaným podľa stavu. Odpoveď sa píše postupne, preto sa na ňu chodíte pozerať opakovane, rozumný interval je päť až desať sekúnd. Na vyzdvihnutie zostáva, kým konverzácia existuje.

Príklad požiadavky

curl -H "X-Api-Key: api-…" \
  https://<vaša-instancia>/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85/messages/9c2e5b71-0f4d-4c8a-9a11-6b7e2f0d5c33

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

Streamuje jednu odpoveď priebežne cez Server-Sent Events, namiesto opakovaného vyzdvihovania.

Parametre

chatId string, povinné, v ceste. UUID konverzácie.
messageId string, povinné, v ceste. UUID odpovede agenta.

Vracia

Prúd text/event-stream. Každá udalosť message nesie aktuálnu podobu odpovede v rovnakom tvare ako POST /api/v1/chats; posledná udalosť sa menuje completed a stream ňou končí.

event: message
data: {"id":"9c2e5b71-…","chatId":"3f8b1a20-…","status":"in_progress","text":"Výpovedné lehoty"}

event: completed
data: {"id":"9c2e5b71-…","chatId":"3f8b1a20-…","status":"completed","text":"Výpovedné lehoty v zmluve sú nastavené takto…"}

Príklad požiadavky

curl -N -H "X-Api-Key: api-…" \
  https://<vaša-instancia>/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85/messages/9c2e5b71-0f4d-4c8a-9a11-6b7e2f0d5c33/events

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

Streamuje dianie celej konverzácie cez Server-Sent Events. Zostáva otvorený aj medzi otázkami, hodí sa pre integráciu, ktorá konverzáciu sleduje dlhodobo.

Parametre

chatId string, povinné, v ceste. UUID konverzácie.

Vracia

Prúd text/event-stream v rovnakom tvare ako u streamu jednej odpovede: udalosť message pre každú zmenu poslednej odpovede v konverzácii a completed, akonáhle je hotová.

Príklad požiadavky

curl -N -H "X-Api-Key: api-…" \
  https://<vaša-instancia>/api/v1/chats/3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85/events

OpenAPI špecifikácia

Strojovo čitateľné schéma celého API nájdete v openapi.yaml. Načítate ho do Postmanu, Insomnie alebo generátora klientov.

Ako zaobchádzať s kľúčom a čo znamenajú chybové kódy, popisuje Integrácia cez API.