CODEXIS AI
CODEXIS AI AgentIntegraceIntegrace přes APIEndpointy API v1

Endpointy API v1

Reference Codexis AI agent API: volání, parametry, odpovědi a příklady požadavků s autentizací pomocí API klíče.

Referenci rozšířeného rozhraní najdete u REST API v2.

Base URL: https://vm.codexis.ai. Všechny requesty vyžadují hlavičku X-Api-Key. Příklady používají proměnnou CODEXIS_API_KEY.

Autentizace a HTTP chyby.

Virtuální počítač

Chat

Přílohy

Soubory

Virtuální počítač

Pro zpracování dotazu musí být virtuální počítač ve stavu RUNNING.

GET /api/v1/vm

Vrátí stav virtuálního počítače.

Vrací

{ "status": "RUNNING" }

200. status: RUNNING, STOPPED, STARTING, STOPPING.

Příklad požadavku

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

POST /api/v1/vm/start

Spustí virtuální počítač.

Vrací

{ "status": "STARTING" }

202. Stav ověřujte přes GET /api/v1/vm do RUNNING.

Příklad požadavku

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

POST /api/v1/vm/stop

Vypne virtuální počítač.

Vrací

{ "status": "STOPPING" }

202. Stav ověřujte přes GET /api/v1/vm do STOPPED.

Příklad požadavku

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

Číselníky

Accept-Language: cs, en, sk. Výchozí jazyk popisků: cs.

GET /api/v1/models

Vrátí modely a jejich nastavení.

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,
    "disabled": false,
    "supportsWebSearch": true,
    "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: hodnota pro model.
  • provider: OPENAI, ANTHROPIC, GOOGLE, TENSOR_X, OPENROUTER, CODEXIS.
  • status: dostupnost poskytovatele, UP, DEGRADED, DOWN, UNKNOWN.
  • default: výchozí model.
  • disabled: model je vypnutý pro nové dotazy.
  • supportsWebSearch: podpora webSearchEnabled.
  • settings: povolené dvojice key a options[].value. Pro disabled je seznam prázdný.

Příklad požadavku

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

GET /api/v1/jurisdictions

Vrátí dostupné právní řády.

Vrací

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

200. Hodnoty id patří do jurisdictions dotazu.

Příklad požadavku

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

GET /api/v1/skills

Vrátí dovednosti, nejpoužívanější první.

Vrací

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

200. V skillIds lze použít id, name nebo fullName.

Příklad požadavku

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

GET /api/v1/agents

Vrátí agenty.

Vrací

200. Stejná struktura jako dovednosti. agentId přijímá id, name nebo fullName.

Příklad požadavku

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

Přílohy

POST /api/v1/attachments

Nahraje přílohy pro zprávu.

Parametry

multipart/form-data

  • files pole souborů, povinné, multipart. Opakujte pole pro každý soubor. Každý soubor musí mít název a neprázdný obsah.

Vrací

[
  {
    "id": "62c96c7a-92f7-4b36-b1b8-6e124bc85502",
    "name": "smlouva.pdf",
    "size": 284913,
    "createdAt": "2026-09-09T09:12:41Z"
  }
]

201. Pole příloh, i pro jeden soubor. size je v bajtech, createdAt v ISO 8601. ID předejte jako attachmentIds do POST /api/v1/chats.

Odeslání zprávy přesune přílohu do konverzace a spotřebuje její ID. Pro další přiložení soubor nahrajte znovu.

Příklad požadavku

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

Soubory

Všechny souborové endpointy vyžadují chatId v query. Cesty patří pracovnímu prostředí dané konverzace.

POST /api/v1/files

Nahraje soubor do konverzace.

Parametry

multipart/form-data

  • chatId string (UUID), povinné, query. Identifikátor konverzace.
  • file soubor, povinné, multipart. Neprázdný soubor s názvem.
  • destination string, volitelné, multipart. Existující cílová složka. Výchozí: /home/codexis.

Vrací

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

201. path slouží pro download, delete nebo odkaz v textu dotazu se stejným chatId. size je v bajtech.

Příklad požadavku

curl -X POST -F "file=@smlouva.pdf" -H "X-Api-Key: $CODEXIS_API_KEY" \
  "https://vm.codexis.ai/api/v1/files?chatId=3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85"

GET /api/v1/files/{path}

Stáhne soubor.

Parametry

  • chatId string (UUID), povinné, query. Identifikátor konverzace.
  • path string, povinné, path. Cesta z uploadu nebo výpisu složky. Lomítka zachovejte, ostatní speciální znaky URL-enkódujte.

Vrací

200. Binární stream s hlavičkami Content-Type, Content-Length a Content-Disposition.

Příklad požadavku

curl -o smlouva.pdf -H "X-Api-Key: $CODEXIS_API_KEY" \
  "https://vm.codexis.ai/api/v1/files/home/codexis/smlouva.pdf?chatId=3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85"

GET /api/v1/directories

Vypíše /home/codexis dané konverzace.

Parametry

  • chatId string (UUID), povinné, query. Identifikátor konverzace.

Vrací

200. Stejný formát jako výpis složky.

Příklad požadavku

curl -H "X-Api-Key: $CODEXIS_API_KEY" \
  "https://vm.codexis.ai/api/v1/directories?chatId=3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85"

GET /api/v1/directories/{path}

Vypíše jednu úroveň složky bez skrytých položek.

Parametry

  • chatId string (UUID), povinné, query. Identifikátor konverzace.
  • path string, povinné, path. Cesta složky v pracovním prostředí konverzace.

Vrací

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

200. entries[].path použijte se stejným chatId. entries[].type: FILE, DIRECTORY, SYMLINK, OTHER.

Příklad požadavku

curl -H "X-Api-Key: $CODEXIS_API_KEY" \
  "https://vm.codexis.ai/api/v1/directories/home/codexis?chatId=3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85"

DELETE /api/v1/files/{path}

Smaže soubor nebo složku.

Parametry

  • chatId string (UUID), povinné, query. Identifikátor konverzace.
  • path string, povinné, path. Cesta z uploadu nebo výpisu složky. Lomítka zachovejte, ostatní speciální znaky URL-enkódujte.
  • recursive boolean, volitelné, query. Smazání složky včetně obsahu. Výchozí: false.

Vrací

204, prázdné tělo. Neprázdná složka vyžaduje recursive=true.

Příklad požadavku

curl -X DELETE -H "X-Api-Key: $CODEXIS_API_KEY" \
  "https://vm.codexis.ai/api/v1/files/home/codexis/smlouva.pdf?chatId=3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85"

POST /api/v1/directories/{path}

Vytvoří složku. Nadřazená složka musí existovat.

Parametry

  • chatId string (UUID), povinné, query. Identifikátor konverzace.
  • path string, povinné, path. Cesta složky v pracovním prostředí konverzace.

Vrací

{
  "name": "dokumenty",
  "path": "/home/codexis/dokumenty"
}

201. path lze použít jako destination uploadu.

Příklad požadavku

curl -X POST -H "X-Api-Key: $CODEXIS_API_KEY" \
  "https://vm.codexis.ai/api/v1/directories/home/codexis/dokumenty?chatId=3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85"

Konverzace

POST /api/v1/chats

Odešle dotaz.

Parametry

application/json

  • input string, povinné. Neprázdný text dotazu.
  • chatId string (UUID), volitelné. Existující konverzace; vynecháním vznikne nová. Existující konverzace zachovává model, settings, jurisdictions a webSearchEnabled.
  • agentId string, volitelné. id, name nebo fullName z GET /api/v1/agents. Výchozí: výchozí agent účtu.
  • skillIds string[], volitelné. id, name nebo fullName z GET /api/v1/skills.
  • attachmentIds string[] (UUID), volitelné. Jednorázová ID z POST /api/v1/attachments.
  • model string, volitelné. id z GET /api/v1/models. Výchozí: model s default: true. Neznámé ID vrací 400.
  • jurisdictions string[], volitelné. Hodnoty id z GET /api/v1/jurisdictions.
  • webSearchEnabled boolean, volitelné. Vyžaduje model s supportsWebSearch: true. Výchozí: false.
  • settings pole objektů, volitelné. Dvojice key a value podle settings v GET /api/v1/models.

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

202 se stavem in_progress, případně 201 se stavem completed.

  • id: UUID zprávy agenta.
  • chatId: UUID konverzace pro další dotazy.
  • text: dosavadní odpověď v Markdownu. Citace obsahuje parts.
  • parts: strukturované části odpovědi.
  • createdAt: ISO 8601.

Příklad požadavku

curl -X POST -H "X-Api-Key: $CODEXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Zkontroluj výpovědní lhůty v přiložené smlouvě.", "attachmentIds": ["62c96c7a-92f7-4b36-b1b8-6e124bc85502"]}' \
  https://vm.codexis.ai/api/v1/chats

Pokračování v konverzaci

Pro pokračování pošlete stejné chatId.

curl -X POST -H "X-Api-Key: $CODEXIS_API_KEY" \
  -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

Vrátí konverzace od poslední aktivity.

Parametry

  • offset integer, volitelné, query. Počet přeskočených konverzací, minimum 0. Výchozí: 0.
  • limit integer, volitelné, query. Počet výsledků, 1 až 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
}

200. status: in_progress při generování odpovědi, jinak completed.

Příklad požadavku

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

GET /api/v1/chats/{chatId}

Vrátí konverzaci a zprávy v chronologickém pořadí.

Parametry

  • chatId string (UUID), povinné, path. Identifikátor 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": [] }
  ]
}

200. chat odpovídá položce výpisu konverzací. messages[].role: USER nebo ASSISTANT; odpovědi obsahují parts.

Příklad požadavku

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

DELETE /api/v1/chats/{chatId}

Zastaví běžící odpověď a smaže konverzaci se zprávami.

Parametry

  • chatId string (UUID), povinné, path. Identifikátor konverzace.

Vrací

204, prázdné tělo. Neexistující konverzace: 404.

Příklad požadavku

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

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

Zastaví generování odpovědi. Dokončenou konverzaci ponechá beze změny.

Parametry

  • chatId string (UUID), povinné, path. Identifikátor konverzace.

Vrací

202. Souhrn konverzace; během zastavování může mít status: in_progress.

Příklad požadavku

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

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

Vrátí aktuální stav odpovědi.

Parametry

  • chatId string (UUID), povinné, path. Identifikátor konverzace.
  • messageId string (UUID), povinné, path. Pole id z odpovědi na POST /api/v1/chats.

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…"
}

200. Stejný objekt jako POST /api/v1/chats, dostupný po dobu existence konverzace. Pro průběžné změny použijte SSE.

Příklad požadavku

curl -H "X-Api-Key: $CODEXIS_API_KEY" \
  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

SSE stream jedné odpovědi.

Parametry

  • chatId string (UUID), povinné, path. Identifikátor konverzace.
  • messageId string (UUID), povinné, path. Pole id z odpovědi na POST /api/v1/chats.

Vrací

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…"}

200, text/event-stream. Událost message obsahuje aktuální odpověď. Událost completed ukončí stream.

Příklad požadavku

curl -N -H "X-Api-Key: $CODEXIS_API_KEY" \
  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

SSE stream konverzace. Zůstává otevřený mezi dotazy.

Parametry

  • chatId string (UUID), povinné, path. Identifikátor konverzace.

Vrací

200, text/event-stream. Události message a completed mají formát streamu odpovědi a týkají se poslední odpovědi v konverzaci.

Příklad požadavku

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

Části odpovědi

text obsahuje Markdown odpovědi. parts obsahuje její strukturované části v pořadí vzniku.

{
  "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.

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

parts se mění do stavu completed.

OpenAPI specifikace

openapi.yaml

REST API v2

Vytvoření projektu a chatu, příloha, odeslání zprávy a průběžná odpověď přes REST API v2.

Práce z příkazové řádky

Přihlaste CLI, vytvořte projekt a chat, pošlete přílohu a sledujte odpověď CODEXIS AI Agenta.