REST API v2

Cez Codexis AI agent API vytvoríte projekt a chat, priložíte súbor a prečítate priebežnú aj hotovú odpoveď. Nasledujúci postup používa API kľúč, Bash, curl, jq a uuidgen. Príkazy spúšťajte v rovnakom termináli.

Postup tvorí POST projekt a chat, POST príloha, POST správa a GET priebežná odpoveď. Úplný kontrakt je v OpenAPI v2.

Pripojenie účtuCopy Anchor Link

Použite API kľúč svojho účtu a posielajte ho v hlavičke X-Api-Key. Základná adresa v2 je https://vm.codexis.ai/api/v2. Kľúč do terminálu zadajte skryto nasledujúcim príkazom.

set -o pipefail
read -r -s -p 'API kľúč: ' CODEXIS_API_KEY
printf '\n'
export CODEXIS_API_KEY
CODEXIS_API_URL='https://vm.codexis.ai/api/v2'

GET /api/v2/meCopy Anchor Link

Overte, pod ktorým účtom budete pracovať. Odpoveď obsahuje id, email a name vlastníka kľúča.

curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  "$CODEXIS_API_URL/me" | jq

Výber modelu a dostupných funkciíCopy Anchor Link

GET /api/v2/modelsCopy Anchor Link

Katalóg obsahuje modely vrátane dostupnosti pre účet, predvoleného výberu a podporovaných funkcií. Nastavenia konkrétneho modelu načítate cez GET /api/v2/models/{modelId}; cez POST /api/v2/models/{modelId}/configuration pošlete objekt fields a získate vyhodnotenú konfiguráciu s odhadom ceny.

curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  "$CODEXIS_API_URL/models?limit=10" | jq

Stránkované zoznamy vracajú items a nextCursor. Ďalšiu stránku načítate s rovnakými filtrami a hodnotou nextCursor v parametri cursor; null označuje koniec zoznamu. K dispozícii sú tiež katalógy /jurisdictions, /tools, /workflow-templates a oprávnenia účtu /me/features, všetky pod základnou adresou v2.

Projekt a chatCopy Anchor Link

POST /api/v2/projectsCopy Anchor Link

Vytvorte projekt a uložte jeho id. Úspešné vytvorenie vracia HTTP 201 a údaje projektu.

project=$(curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ukážka API","description":"Kontrola dokumentu"}' \
  "$CODEXIS_API_URL/projects")
project_id=$(printf '%s' "$project" | jq -er '.id')

POST /api/v2/chatsCopy Anchor Link

V projekte založte chat s oprávnením READ_ONLY. Model sa zvolí podľa predvoleného nastavenia účtu. Odpoveď HTTP 201 obsahuje id nového chatu; prácu agenta spustíte odoslaním správy v ďalšom kroku.

chat_request=$(jq -n --arg projectId "$project_id" \
  '{title: "Kontrola dokumentu", projectId: $projectId, capabilities: "READ_ONLY"}')
chat=$(curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "$chat_request" \
  "$CODEXIS_API_URL/chats")
chat_id=$(printf '%s' "$chat" | jq -er '.id')

Metadáta chatu upravíte cez PATCH /api/v2/chats/{chatId}. Polia title, pinned a capabilities meníte jednotlivo. Projekt upravujete cez PUT /api/v2/projects/{projectId}, ktorý očakáva všetky editovateľné polia opísané v schéme PublicProjectReplacement.

PrílohaCopy Anchor Link

POST /api/v2/attachmentsCopy Anchor Link

Nahrajte jeden súbor v multipart poli file. Príklad vytvorí krátky textový podklad a uloží ID nahranej prílohy. Pre viac príloh vykonajte samostatné nahranie každého súboru a ich ID odovzdajte v jednom poli attachmentIds.

printf '%s\n' 'Podklady: zmluva sa obnovuje 1. januára. Výpoveď je potrebné doručiť o 30 dní skôr.' > api-example.txt
attachment=$(curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  -F 'file=@api-example.txt' \
  "$CODEXIS_API_URL/attachments")
attachment_id=$(printf '%s' "$attachment" | jq -er '.id')

HTTP 201 vracia metadáta prílohy vrátane id, name, size a contentUrl. Predvolený limit požiadavky je 50 MiB vrátane multipart hlavičiek. Nahraná príloha čaká na priradenie k správe; pri príprave správy sa spotrebuje jej ID. Nepoužitú prílohu odstránite cez DELETE /api/v2/attachments/{attachmentId}.

Odoslanie a potvrdenie správyCopy Anchor Link

POST /api/v2/chats/{chatId}/messagesCopy Anchor Link

Pre každú novú správu vytvorte UUID do hlavičky Idempotency-Key. Uložte ho spolu s telom požiadavky, aby ste mohli zistiť výsledok aj po prerušení spojenia. Požiadavka obsahuje text message, prílohy attachmentIds, alebo oboje.

request_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
message_request=$(jq -n --arg attachmentId "$attachment_id" \
  '{message: "Prečítaj prílohu a zhrň jej obsah.", attachmentIds: [$attachmentId]}')
if receipt=$(curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $request_id" \
  -d "$message_request" \
  "$CODEXIS_API_URL/chats/$chat_id/messages"); then
  message_id=$(printf '%s' "$receipt" | jq -er '.assistantMessageId')
  printf '%s\n' "$receipt" | jq
else
  printf 'Odoslanie nebolo potvrdené. Načítajte uložené potvrdenie s pôvodným requestId %s podľa nasledujúceho kroku.\n' "$request_id"
fi

VraciaCopy Anchor Link

{
  "status": "accepted",
  "requestId": "f07b5a7d-fd34-40ad-9957-3251d9f26841",
  "chatId": "6fecc96e-8f93-4d93-b7c7-0b7591c9a2d1",
  "createdAt": "2026-10-02T10:00:00Z",
  "userMessageId": "0cb83f6a-85c1-426a-9372-51b4c48ee67f",
  "assistantMessageId": "b647181c-ec42-4993-a17d-d2233078a70c"
}

HTTP 202 potvrdzuje prijatie správy. assistantMessageId použijete na sledovanie odpovede a jej načítanie. Dokončenie práce určíte podľa stavu opísaného nižšie.

GET /api/v2/chats/{chatId}/message-requests/{requestId}Copy Anchor Link

Po prerušení odosielania načítajte uložené potvrdenie rovnakým UUID. Stav accepted obsahuje ID prijatých správ; rejected obsahuje kód odmietnutia a errorMessageId. Stav unresolved znamená, že výsledok prijatia vyžaduje overenie pred ďalším odoslaním.

curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  "$CODEXIS_API_URL/chats/$chat_id/message-requests/$request_id" | jq

Pri pôvodne prijatej správe vráti opakovanie rovnakého kľúča a rovnakého vstupu pôvodné potvrdenie. Pri odmietnutej alebo zatiaľ nevyriešenej požiadavke vráti opakované odoslanie HTTP 409; výsledok overte cez GET /api/v2/chats/{chatId}/message-requests/{requestId}. Zmena vstupu pod rovnakým kľúčom vráti konflikt HTTP 409; pre novú otázku vytvorte nový kľúč. Pri opakovaní zachovajte aj pôvodné ID príloh.

Priebežná a hotová odpoveďCopy Anchor Link

GET /api/v2/chats/{chatId}/messages/{messageId}/eventsCopy Anchor Link

Sledujte odpoveď cez Server-Sent Events. Prepínač -N vypne vyrovnávaciu pamäť curl, takže sa prijaté dáta zobrazujú priebežne.

curl --fail-with-body -sS -N \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  -H 'Accept: text/event-stream' \
  "$CODEXIS_API_URL/chats/$chat_id/messages/$message_id/events"

Každá udalosť snapshot obsahuje aktuálny stav execution, správu message a postup čiastkových agentov a automatizácií. Textové časti správy majú type: "text" a text s citáciami v citedMarkdown. Pri vykreslení nahrádzajte predchádzajúci obsah novým snapshotom. Po opätovnom pripojení dostanete aktuálny stav; odpojením klienta ponecháte pokračujúcu prácu agenta bežať.

GET /api/v2/chats/{chatId}/messages/{messageId}/statusCopy Anchor Link

Stav môžete načítať aj jednorazovo. active označuje prebiehajúcu prácu, waiting čakanie na vstup, completed úspešné dokončenie, failed chybu a stopped zastavenie. Pri unknown najprv overte stav ďalším načítaním. Stream končí po konečnom stave completed, failed alebo stopped.

curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  "$CODEXIS_API_URL/chats/$chat_id/messages/$message_id/status" | jq '.execution'

GET /api/v2/chats/{chatId}/messages/{messageId}Copy Anchor Link

Po stave completed načítajte hotovú správu. Príklad vypíše jej textové časti s citáciami v Markdowne; celá odpoveď obsahuje aj ostatné časti správy. Históriu získate cez GET /api/v2/chats/{chatId}/messages.

curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  "$CODEXIS_API_URL/chats/$chat_id/messages/$message_id" \
  | jq -r '.parts[] | select(.type == "text") | .citedMarkdown'

Uložené definície agentovCopy Anchor Link

GET /api/v2/agentsCopy Anchor Link

Načítajte vlastných agentov aj agentov dostupných z doplnkov. Pri každom sledujte editable a deletable. Novú vlastnú definíciu vytvoríte cez POST /api/v2/agents, upravíte cez PUT /api/v2/agents/{agentId} a odstránite cez DELETE /api/v2/agents/{agentId}.

curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  "$CODEXIS_API_URL/agents?limit=10" | jq

Pri vytvorení aj úprave pošlite všetky polia schémy PublicAgentInput. Preklady v displayName, summary a examplePrompts sa pri úprave zlučujú podľa jazyka cs, en alebo sk; ostatné hodnoty sa nahrádzajú. Na načítanie definície so všetkými prekladmi použite GET /api/v2/agents/{agentId}.

Poľom agentId pri založení chatu prevezmete nastavenia definície. Do konkrétnej správy pridajte jej ID v poli agentIds, aby agent dostal jej inštrukcie.

Otázky a schválenia počas práceCopy Anchor Link

GET /api/v2/chats/{chatId}/messages/{messageId}/interactionsCopy Anchor Link

Keď agent čaká na vašu odpoveď, načítajte otvorené otázky a návrhy automatizácií. S každou odpoveďou uchovajte vrátené toolCallId a revision, aby sa vzťahovala ku konkrétnemu zobrazenému návrhu.

curl --fail-with-body -sS \
  -H "X-Api-Key: $CODEXIS_API_KEY" \
  "$CODEXIS_API_URL/chats/$chat_id/messages/$message_id/interactions" | jq

Na otázku odpoviete cez POST /api/v2/chats/{chatId}/messages/{messageId}/interactions/{toolCallId}/answer podľa PublicQuestionAnswerRequest. Návrh vybavíte cez zodpovedajúcu cestu /decision podľa PublicWorkflowDecisionRequest; použite RUN, REQUEST_CHANGES s textom feedback, alebo CANCEL. Po potvrdení HTTP 202 ďalej sledujte stav správy. Pri HTTP 409 znovu načítajte interakciu a jej aktuálnu revíziu.

Chyby a ďalšie krokyCopy Anchor Link

Pri chybe vyhodnoťte HTTP stav. Odpoveď typu application/problem+json obsahuje code, opis detail a identifikátor requestId, ktorý priložte k požiadavke na podporu.

Všetky cesty, povinné polia, limity a podoby odpovedí obsahuje OpenAPI v2 na stiahnutie. Pre prácu z terminálu pokračujte na CLI; pre prepojenie s AI klientom na MCP.