CODEXIS AI
CODEXIS AI AgentIntegrationsAPI integration

Endpoint reference

A reference of every Codexis AI agent API call. Paths are relative to the address of your instance and every call carries the X-Api-Key header. Creating a key, the error codes and the security practice are covered by API integration.

Virtual machine

The agent runs on a virtual machine that is yours alone. It processes a question while the machine is in the RUNNING state.

GET /api/v1/vm

Returns the state of the virtual machine your agent runs on.

Parameters

None.

Returns

{ "status": "RUNNING" }

The state is one of RUNNING, STOPPED, STARTING, STOPPING.

Example request

curl -H "X-Api-Key: api-…" https://<your-instance>/api/v1/vm

POST /api/v1/vm/start

Starts the virtual machine.

Parameters

None.

Returns

{ "status": "STARTING" }

The response is a 202. Reaching RUNNING takes tens of seconds, confirm it with GET /api/v1/vm.

Example request

curl -X POST -H "X-Api-Key: api-…" https://<your-instance>/api/v1/vm/start

POST /api/v1/vm/stop

Shuts the virtual machine down.

Parameters

None.

Returns

{ "status": "STOPPING" }

The response is a 202. The shutdown itself takes a while.

Example request

curl -X POST -H "X-Api-Key: api-…" https://<your-instance>/api/v1/vm/stop

Files

POST /api/v1/files

Uploads a file into the agent's workspace so that a question can refer to it.

Parameters

The request body is multipart/form-data.

  • file file, required. The contents of the uploaded file. The file needs a name and some content.
  • destination string, optional. Target folder in the workspace. Defaults to the upload folder.

Returns

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

The response is a 201. You pass the path value in filePaths when sending a question, and size is the size in bytes.

Example request

curl -X POST -H "X-Api-Key: api-…" \
  -F "file=@contract.pdf" \
  https://<your-instance>/api/v1/files

Conversations

POST /api/v1/chats

Sends a question to the agent, either into a new conversation or into an existing one.

Parameters

The request body is JSON.

  • input string, required. The text of the question. The only field you have to send.
  • chatId string, optional. UUID of the conversation the question is appended to. Defaults to a new conversation. On a continuation, model, fields, jurisdictions and webSearchEnabled are taken over from the conversation.
  • agentId string, optional. The agent that should answer, given by its ID, name or full name. Defaults to your default agent.
  • skillIds array of strings, optional. The skills the agent should have available for this question, given by their IDs, names or full names.
  • filePaths array of strings, optional. Workspace paths of the files to attach to the question. Take the values from the path field of the upload response.
  • model string, optional. The language model. One of 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). Defaults to your instance's model.
  • jurisdictions array of strings, optional. The jurisdictions the agent should search. Values CZ, SK, EU, AT, NL, FR.
  • webSearchEnabled boolean, optional. Lets the agent search the web as well. Default: false.
  • fields array of objects, optional. Model fine-tuning, the same options as in the application.
    • key string. Name of the option.
    • value string. Value of the option.

Returns

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

A 202 arrives at once, before the agent has finished thinking. If the agent manages to answer straight away, a 201 arrives with the status completed.

  • id string. UUID of the agent's answer. Together with chatId you collect the answer by it.
  • chatId string. UUID of the conversation. Send it in your next question and the conversation continues.
  • status string. One of in_progress and completed. With the status completed the answer text is whole.
  • text string. The text of the answer written so far.
  • model string. The language model the conversation answers with.
  • createdAt string. When the answer was created, in ISO 8601 format.

Example request

curl -X POST -H "X-Api-Key: api-…" \
  -H "Content-Type: application/json" \
  -d '{"input": "Check the notice periods in the attached contract.", "filePaths": ["/uploads/contract.pdf"]}' \
  https://<your-instance>/api/v1/chats

Continuing a conversation

To follow up, send another question with the same chatId. The agent knows the whole exchange so far.

curl -X POST -H "X-Api-Key: api-…" \
  -H "Content-Type: application/json" \
  -d '{"chatId": "3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85", "input": "And what about the warranties?"}' \
  https://<your-instance>/api/v1/chats

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

Collects the answer to a question.

Parameters

  • chatId string, required, in the path. UUID of the conversation the answer belongs to. Take it from the chatId field of the send response.
  • messageId string, required, in the path. UUID of the agent's answer. Take it from the id field of the send response.

Returns

{
  "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": "The notice periods in the contract are set out as follows…"
}

The same object as POST /api/v1/chats, with the text filled in according to the status. The answer is written gradually, so you come back for it repeatedly, a sensible interval being five to ten seconds. It stays available for as long as the conversation exists.

Example request

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

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

Streams one answer as it is written, over Server-Sent Events, instead of collecting it repeatedly.

Parameters

  • chatId string, required, in the path. UUID of the conversation.
  • messageId string, required, in the path. UUID of the agent's answer.

Returns

A text/event-stream. Every message event carries the current shape of the answer in the same form as POST /api/v1/chats; the last event is named completed and ends the stream.

event: message
data: {"id":"9c2e5b71-…","chatId":"3f8b1a20-…","status":"in_progress","text":"The notice periods"}

event: completed
data: {"id":"9c2e5b71-…","chatId":"3f8b1a20-…","status":"completed","text":"The notice periods in the contract are set out as follows…"}

Example request

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

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

Streams everything happening in a conversation, over Server-Sent Events. It stays open between questions, which suits an integration that watches a conversation over a long period.

Parameters

  • chatId string, required, in the path. UUID of the conversation.

Returns

A text/event-stream in the same form as the single-answer stream: a message event for every change of the latest answer in the conversation, and completed once it's done.

Example request

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

OpenAPI specification

The machine-readable schema of the whole API is in openapi.yaml. Load it into Postman, Insomnia or a client generator.

For how to handle the key and what the error codes mean, see API integration.

API integration

Previous

AI 2.0 FAQ

Next