Prehľad endpointov | CODEXIS AI Agent

Referencia všetkých volaní Codexis AI agent API. Cesty sú relatívne k https://vm.codexis.ai 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.

Virtuálny stroj

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č.

Chat

POST /api/v1/chats pošle otázku agentovi.
GET /api/v1/chats vypíše vaše konverzácie.
GET /api/v1/chats/{chatId} vráti konverzáciu aj s priebehom.
DELETE /api/v1/chats/{chatId} zmaže konverzáciu.
POST /api/v1/chats/{chatId}/stop zastaví rozpísanú odpoveď.
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.
GET /api/v1/models vráti dostupné modely a ich voľby.
GET /api/v1/jurisdictions vráti dostupné právne poriadky.
GET /api/v1/skills vráti vaše schopnosti.
GET /api/v1/agents vráti vašich agentov.

Súbory

POST /api/v1/files nahrá súbor do pracovného priestoru agenta.
GET /api/v1/files/{path} stiahne súbor z pracovného priestoru.
GET /api/v1/directories/{path} vypíše obsah priečinka.

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://vm.codexis.ai/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://vm.codexis.ai/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://vm.codexis.ai/api/v1/vm/stop

Číselníky

Hodnoty, ktoré prijíma POST /api/v1/chats, si nemusíte pamätať — API ich vie vymenovať. Popisky ctia hlavičku Accept-Language (cs, en, sk); bez nej prídu po česky.

GET `/api/v1/models`

Vráti jazykové modely, ktorými môže konverzácia odpovedať, vrátane volieb, ktoré každý model prijíma.

Parametre

Žiadne.

Vracia

[
  {
    "id": "GPT_5_6_TERRA",
    "label": "GPT-5.6 Terra",
    "description": "Vyvážená konfigurácia GPT-5.6 medzi inteligenciou a cenou.",
    "provider": "OPENAI",
    "status": "UP",
    "default": true,
    "deprecated": false,
    "settings": [
      {
        "key": "reasoningEffort",
        "label": "Úroveň uvažovania",
        "options": [
          { "value": "LOW", "label": "Nízka" },
          { "value": "MEDIUM", "label": "Stredná" },
          { "value": "HIGH", "label": "Vysoká" }
        ],
        "defaultValue": "MEDIUM"
      }
    ]
  }
]

id string. Hodnota pre pole model pri posielaní otázky.
provider string. Jedna z hodnôt OPENAI, ANTHROPIC, GOOGLE.
status string. Aktuálna dostupnosť poskytovateľa: UP, DEGRADED, DOWN, UNKNOWN.
default boolean. Model použitý, keď model v otázke vynecháte.
deprecated boolean. Model je na odchode; zostáva funkčný, ale nevyberajte ho pre nové integrácie.
settings pole objektov. Voľby, ktoré model prijíma. Vybrané hodnoty posielate ako settings otázky, key a options[].value presne tak, ako tu stoja. Zastarané modely žiadne voľby neponúkajú.

Príklad požiadavky

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

GET `/api/v1/jurisdictions`

Vráti právne poriadky, v ktorých agent vie hľadať.

Parametre

Žiadne.

Vracia

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

Hodnotu id posielate v poli jurisdictions otázky.

Príklad požiadavky

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

GET `/api/v1/skills`

Vráti schopnosti dostupné na vašom účte, najpoužívanejšie prvé.

Parametre

Žiadne.

Vracia

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

V poli skillIds otázky môžete použiť id, name aj fullName.

Príklad požiadavky

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

GET `/api/v1/agents`

Vráti agentov dostupných na vašom účte.

Parametre

Žiadne.

Vracia

Rovnaký tvar ako pri schopnostiach: id, name, fullName a description. V poli agentId otázky môžete použiť ktorúkoľvek z prvých troch hodnôt.

Príklad požiadavky

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

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://vm.codexis.ai/api/v1/files

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

Stiahne súbor z pracovného priestoru. Obsah sa streamuje, takže veľkosť súboru nehrá rolu.

Parametre

path, povinné, v ceste. Cesta súboru tak, ako ju vracia nahranie (path) alebo výpis priečinka (entries[].path). Pripája sa za /api/v1/files aj s lomkami, nič sa nekóduje.

Vracia

Binárny obsah súboru s jeho skutočným Content-Type, dĺžkou v Content-Length a názvom v Content-Disposition (UTF-8, takže diakritika v názvoch funguje).

404, na tejto ceste žiadny súbor nie je.
400, cesta vedie na priečinok.
403, cesta mieri mimo váš pracovný priestor.

Príklad požiadavky

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

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

Vypíše obsah priečinka pracovného priestoru — jednu úroveň, bez skrytých súborov a bez obsahu súborov. Bez cesty (GET /api/v1/directories) vypíše domovský priečinok.

Parametre

path, voliteľné, v ceste. Cesta priečinka, pripojená za /api/v1/directories aj s lomkami. Východiskový je domovský priečinok.

Vracia

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

entries[].type string. Jedna z hodnôt FILE, DIRECTORY, SYMLINK, OTHER.
entries[].path string. Cesta použiteľná na stiahnutie, priloženie k otázke aj zmazanie.
Do podpriečinka sa zanoríte ďalším volaním s jeho cestou.

Príklad požiadavky

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

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, settings, 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. Ponuku vracia GET /api/v1/agents. 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. Ponuku vracia GET /api/v1/skills.
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, hodnota id z GET /api/v1/models, napríklad GPT_5_6_TERRA alebo CLAUDE_SONNET_5. Východiskový je model označený v ponuke ako default. Neznámy model vráti 400 so zoznamom platných hodnôt.
jurisdictions pole reťazcov, voliteľné. Právne poriadky, v ktorých má agent hľadať, hodnoty id z GET /api/v1/jurisdictions.
webSearchEnabled boolean, voliteľné. Povolí agentovi hľadať aj na internete. Východisková hodnota: false.
settings pole objektov, voliteľné. Doladenie modelu, rovnaké voľby ako v aplikácii. Ktoré voľby model prijíma, hovorí pole settings v GET /api/v1/models.
- 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://vm.codexis.ai/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://vm.codexis.ai/api/v1/chats

GET `/api/v1/chats`

Vypíše vaše konverzácie, pripnuté prvé a potom od najnovšej.

Parametre

offset číslo, voliteľné, v adrese. Koľko konverzácií preskočiť. Východisková hodnota: 0.
limit číslo, voliteľné, v adrese. Koľko konverzácií vrátiť, najviac 200. Východisková hodnota: 50.

Vracia

{
  "chats": [
    {
      "chatId": "3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85",
      "title": "Výpovedné lehoty v zmluve",
      "status": "completed",
      "createdAt": "2026-07-30T09:14:22Z",
      "modifiedAt": "2026-07-30T09:16:03Z",
      "model": "GPT_5_6_TERRA",
      "pinned": false,
      "webSearchEnabled": false,
      "jurisdictions": ["SK"]
    }
  ],
  "offset": 0,
  "limit": 50,
  "totalCount": 1
}

status je in_progress, kým konverzácia odpovedá, inak completed.

Príklad požiadavky

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

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

Vráti konverzáciu aj s celým doterajším priebehom.

Parametre

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

Vracia

{
  "chat": { "chatId": "3f8b1a20-…", "title": "Výpovedné lehoty v zmluve", "status": "completed" },
  "messages": [
    { "id": "71d3…", "role": "USER", "status": "completed", "text": "Skontroluj výpovedné lehoty…" },
    { "id": "9c2e…", "role": "ASSISTANT", "status": "completed", "text": "Výpovedné lehoty v zmluve…", "parts": [] }
  ]
}

chat objekt. Rovnaký súhrn ako vo výpise konverzácií.
messages pole objektov. Priebeh v poradí, ako vznikal. role je USER, alebo ASSISTANT; odpovede agenta nesú aj parts.

Príklad požiadavky

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

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

Zmaže konverzáciu aj s jej odpoveďami. Prebiehajúca odpoveď sa pred zmazaním zastaví.

Parametre

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

Vracia

Odpoveďou je 204 s prázdnym telom. Neexistujúca konverzácia vráti 404.

Príklad požiadavky

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í odpoveď, ktorú konverzácia práve píše. Pri konverzácii, ktorá nič nepíše, sa nič nestane a vráti sa jej aktuálny stav.

Parametre

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

Vracia

Odpoveďou je 202 so súhrnom konverzácie v rovnakom tvare ako vo výpise. Zastavenie môže ešte chvíľu dobiehať, takže status môže byť stále in_progress.

Príklad požiadavky

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

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://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 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://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 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://vm.codexis.ai/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.