REST API v2

Přes Codexis AI agent API vytvoříte projekt a chat, přiložíte soubor a přečtete průběžnou i hotovou odpověď. Následující postup používá API klíč, Bash, curl, jq a uuidgen. Příkazy spouštějte ve stejném terminálu.

Postup tvoří POST projekt a chat, POST příloha, POST zpráva a GET průběžná odpověď. Úplný kontrakt je v OpenAPI v2.

Připojení účtuCopy Anchor Link

Použijte API klíč svého účtu a posílejte ho v hlavičce X-Api-Key. Základní adresa v2 je https://vm.codexis.ai/api/v2. Klíč do terminálu zadejte skrytě následujícím příkazem.

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

GET /api/v2/meCopy Anchor Link

Ověřte, pod kterým účtem budete pracovat. Odpověď obsahuje id, email a name vlastníka klíče.

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

Výběr modelu a dostupných funkcíCopy Anchor Link

GET /api/v2/modelsCopy Anchor Link

Katalog obsahuje modely včetně dostupnosti pro účet, výchozího výběru a podporovaných funkcí. Nastavení konkrétního modelu načtete přes GET /api/v2/models/{modelId}; přes POST /api/v2/models/{modelId}/configuration pošlete objekt fields a získáte vyhodnocenou konfiguraci s odhadem ceny.

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

Stránkované seznamy vracejí items a nextCursor. Další stránku načtete se stejnými filtry a hodnotou nextCursor v parametru cursor; null označuje konec seznamu. K dispozici jsou také katalogy /jurisdictions, /tools, /workflow-templates a oprávnění účtu /me/features, všechny pod základní adresou v2.

Projekt a chatCopy Anchor Link

POST /api/v2/projectsCopy Anchor Link

Vytvořte projekt a uložte jeho id. Úspěšné vytvoření vrací 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ázka API","description":"Kontrola dokumentu"}' \
  "$CODEXIS_API_URL/projects")
project_id=$(printf '%s' "$project" | jq -er '.id')

POST /api/v2/chatsCopy Anchor Link

V projektu založte chat s oprávněním READ_ONLY. Model se zvolí podle výchozího nastavení účtu. Odpověď HTTP 201 obsahuje id nového chatu; práci agenta spustíte odesláním zprávy v dalším 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')

Metadata chatu upravíte přes PATCH /api/v2/chats/{chatId}. Pole title, pinned a capabilities měníte jednotlivě. Projekt upravujete přes PUT /api/v2/projects/{projectId}, který očekává všechna editovatelná pole popsaná ve schématu PublicProjectReplacement.

PřílohaCopy Anchor Link

POST /api/v2/attachmentsCopy Anchor Link

Nahrajte jeden soubor v multipart poli file. Příklad vytvoří krátký textový podklad a uloží ID nahrané přílohy. Pro více příloh proveďte samostatné nahrání každého souboru a jejich ID předejte v jednom poli attachmentIds.

printf '%s\n' 'Podklady: smlouva se obnovuje 1. ledna. Výpověď je třeba doručit o 30 dní dříve.' > 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 vrací metadata přílohy včetně id, name, size a contentUrl. Výchozí limit požadavku je 50 MiB včetně multipart hlaviček. Nahraná příloha čeká na přiřazení ke zprávě; při přípravě zprávy se spotřebuje její ID. Nepoužitou přílohu odstraníte přes DELETE /api/v2/attachments/{attachmentId}.

Odeslání a potvrzení zprávyCopy Anchor Link

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

Pro každou novou zprávu vytvořte UUID do hlavičky Idempotency-Key. Uložte ho spolu s tělem požadavku, abyste mohli zjistit výsledek i po přerušení spojení. Požadavek obsahuje text message, přílohy attachmentIds, nebo obojí.

request_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
message_request=$(jq -n --arg attachmentId "$attachment_id" \
  '{message: "Přečti přílohu a shrň 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 'Odeslání nebylo potvrzeno. Načtěte uložené potvrzení s původním requestId %s podle následujícího kroku.\n' "$request_id"
fi

VracíCopy 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 potvrzuje přijetí zprávy. assistantMessageId použijete pro sledování odpovědi a její načtení. Dokončení práce určíte podle stavu popsaného níže.

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

Po přerušení odesílání načtěte uložené potvrzení stejným UUID. Stav accepted obsahuje ID přijatých zpráv; rejected obsahuje kód odmítnutí a errorMessageId. Stav unresolved znamená, že výsledek přijetí vyžaduje ověření před dalším odesláním.

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

U původně přijaté zprávy vrátí opakování stejného klíče a stejného vstupu původní potvrzení. U odmítnutého nebo dosud nevyřešeného požadavku vrátí opakované odeslání HTTP 409; výsledek ověřte přes GET /api/v2/chats/{chatId}/message-requests/{requestId}. Změna vstupu pod stejným klíčem vrátí konflikt HTTP 409; pro nový dotaz vytvořte nový klíč. Při opakování zachovejte i původní ID příloh.

Průběžná a hotová odpověďCopy Anchor Link

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

Sledujte odpověď přes Server-Sent Events. Přepínač -N vypne vyrovnávací paměť curl, takže se přijatá data zobrazují průběžně.

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á událost snapshot obsahuje aktuální stav execution, zprávu message a postup dílčích agentů a automatizací. Textové části zprávy mají type: "text" a text s citacemi v citedMarkdown. Při vykreslení nahrazujte předchozí obsah novým snapshotem. Po opětovném připojení obdržíte aktuální stav; odpojením klienta pokračující práci agenta ponecháte běžet.

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

Stav můžete načíst i jednorázově. active označuje probíhající práci, waiting čekání na vstup, completed úspěšné dokončení, failed chybu a stopped zastavení. U unknown nejprve ověřte stav dalším načtením. Stream končí po konečném stavu completed, failed nebo 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 stavu completed načtěte hotovou zprávu. Příklad vypíše její textové části s citacemi v Markdownu; celá odpověď obsahuje i ostatní části zprávy. Historii získáte přes 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é definice agentůCopy Anchor Link

GET /api/v2/agentsCopy Anchor Link

Načtěte vlastní agenty i agenty dostupné z doplňků. U každého sledujte editable a deletable. Novou vlastní definici vytvoříte přes POST /api/v2/agents, upravíte přes PUT /api/v2/agents/{agentId} a odstraníte přes DELETE /api/v2/agents/{agentId}.

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

Při vytvoření i úpravě pošlete všechna pole schématu PublicAgentInput. Překlady v displayName, summary a examplePrompts se při úpravě slučují podle jazyka cs, en nebo sk; ostatní hodnoty se nahrazují. Pro načtení definice se všemi překlady použijte GET /api/v2/agents/{agentId}.

Polem agentId při založení chatu převezmete nastavení definice. Do konkrétní zprávy přidejte její ID v poli agentIds, aby agent dostal její instrukce.

Otázky a schválení během práceCopy Anchor Link

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

Když agent čeká na vaši odpověď, načtěte otevřené otázky a návrhy automatizací. S každou odpovědí uchovejte vrácené toolCallId a revision, aby se vztahovala ke konkrétnímu 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 odpovíte přes POST /api/v2/chats/{chatId}/messages/{messageId}/interactions/{toolCallId}/answer podle PublicQuestionAnswerRequest. Návrh vyřídíte přes odpovídající cestu /decision podle PublicWorkflowDecisionRequest; použijte RUN, REQUEST_CHANGES s textem feedback, nebo CANCEL. Po potvrzení HTTP 202 dál sledujte stav zprávy. Při HTTP 409 znovu načtěte interakci a její aktuální revizi.

Chyby a další krokyCopy Anchor Link

Při chybě vyhodnoťte HTTP stav. Odpověď typu application/problem+json obsahuje code, popis detail a identifikátor requestId, který přiložte k požadavku na podporu.

Všechny cesty, povinná pole, limity a podoby odpovědí obsahuje OpenAPI v2 ke stažení. Pro práci z terminálu pokračujte na CLI; pro propojení s AI klientem na MCP.