Endpoint reference | CODEXIS AI Agent

A reference of every Codexis AI agent API call. Paths are relative to https://vm.codexis.ai 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

GET /api/v1/vm returns the state of the virtual machine.
POST /api/v1/vm/start starts the virtual machine.
POST /api/v1/vm/stop shuts the virtual machine down.

Chat

POST /api/v1/chats sends a question to the agent.
GET /api/v1/chats lists your conversations.
GET /api/v1/chats/{chatId} returns a conversation with its history.
DELETE /api/v1/chats/{chatId} deletes a conversation.
POST /api/v1/chats/{chatId}/stop stops an answer being written.
GET /api/v1/chats/{chatId}/messages/{messageId} collects the answer to a question.
GET /api/v1/chats/{chatId}/messages/{messageId}/events streams one answer as it is written.
GET /api/v1/chats/{chatId}/events streams everything happening in a conversation.
GET /api/v1/models returns the available models and their settings.
GET /api/v1/jurisdictions returns the available jurisdictions.
GET /api/v1/skills returns your skills.
GET /api/v1/agents returns your agents.

Files

POST /api/v1/files uploads a file into the agent's workspace.
GET /api/v1/files/{path} downloads a file from the workspace.
GET /api/v1/directories/{path} lists a workspace folder.

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

Catalogs

You do not have to memorize the values POST /api/v1/chats accepts — the API lists them. Labels honor the Accept-Language header (cs, en, sk); without it they arrive in Czech.

GET `/api/v1/models`

Returns the language models a conversation can answer with, including the settings each model takes.

Parameters

None.

Returns

[
  {
    "id": "GPT_5_6_TERRA",
    "label": "GPT-5.6 Terra",
    "description": "Balanced GPT-5.6 configuration for intelligence and cost.",
    "provider": "OPENAI",
    "status": "UP",
    "default": true,
    "deprecated": false,
    "settings": [
      {
        "key": "reasoningEffort",
        "label": "Reasoning effort",
        "options": [
          { "value": "LOW", "label": "Low" },
          { "value": "MEDIUM", "label": "Medium" },
          { "value": "HIGH", "label": "High" }
        ],
        "defaultValue": "MEDIUM"
      }
    ]
  }
]

id string. The value for the model field when sending a question.
provider string. One of OPENAI, ANTHROPIC, GOOGLE.
status string. Current provider health: UP, DEGRADED, DOWN, UNKNOWN.
default boolean. The model used when you omit model in the question.
deprecated boolean. The model is on its way out; it still works, but do not pick it for new integrations.
settings array of objects. The settings the model takes. Pass chosen values as the question's settings, with key and options[].value exactly as listed. Deprecated models offer no settings.

Example request

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

GET `/api/v1/jurisdictions`

Returns the jurisdictions the agent can search in.

Parameters

None.

Returns

[
  { "id": "CZ", "label": "Czech Republic" },
  { "id": "SK", "label": "Slovakia" }
]

You pass the id value in the question's jurisdictions field.

Example request

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

GET `/api/v1/skills`

Returns the skills available on your account, most used first.

Parameters

None.

Returns

[
  {
    "id": "8f2c9d41-5b7e-4a03-9c66-1d4e8b2a7f50",
    "name": "planner",
    "fullName": "demo-plugin:planner",
    "description": "Plans case-law research"
  }
]

In the question's skillIds field you can use id, name or fullName.

Example request

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

GET `/api/v1/agents`

Returns the agents available on your account.

Parameters

None.

Returns

The same shape as skills: id, name, fullName and description. In the question's agentId field you can use any of the first three.

Example request

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

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

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

Downloads a file from the workspace. The content is streamed, so the file size does not matter.

Parameters

path, required, in the path. The file's path as returned by the upload (path) or the folder listing (entries[].path). It is appended after /api/v1/files including its slashes, nothing is encoded.

Returns

The binary content of the file with its real Content-Type, its length in Content-Length and its name in Content-Disposition (UTF-8, so diacritics in names work).

404, there is no file at this path.
400, the path leads to a folder.
403, the path points outside your workspace.

Example request

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

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

Lists a workspace folder — one level, without hidden files and without file contents. Without a path (GET /api/v1/directories) it lists the home folder.

Parameters

path, optional, in the path. The folder's path, appended after /api/v1/directories including its slashes. Defaults to the home folder.

Returns

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

entries[].type string. One of FILE, DIRECTORY, SYMLINK, OTHER.
entries[].path string. A path usable for downloading, attaching to a question and deleting.
You descend into a subfolder with another call carrying its path.

Example request

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

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, settings, 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. GET /api/v1/agents lists them. 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. GET /api/v1/skills lists them.
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, an id value from GET /api/v1/models, such as GPT_5_6_TERRA or CLAUDE_SONNET_5. Defaults to the model flagged default in the listing. An unknown model returns a 400 with the list of valid values.
jurisdictions array of strings, optional. The jurisdictions the agent should search, id values from GET /api/v1/jurisdictions.
webSearchEnabled boolean, optional. Lets the agent search the web as well. Default: false.
settings array of objects, optional. Model fine-tuning, the same options as in the application. Which settings a model takes is described by the settings field of GET /api/v1/models.
- 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://vm.codexis.ai/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://vm.codexis.ai/api/v1/chats

GET `/api/v1/chats`

Lists your conversations, pinned first, then most recent.

Parameters

offset number, optional, in the query. How many conversations to skip. Default: 0.
limit number, optional, in the query. How many conversations to return, at most 200. Default: 50.

Returns

{
  "chats": [
    {
      "chatId": "3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85",
      "title": "Notice periods in the contract",
      "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
}

status is in_progress while the conversation is answering, otherwise completed.

Example request

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

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

Returns a conversation with its whole history so far.

Parameters

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

Returns

{
  "chat": { "chatId": "3f8b1a20-…", "title": "Notice periods in the contract", "status": "completed" },
  "messages": [
    { "id": "71d3…", "role": "USER", "status": "completed", "text": "Check the notice periods…" },
    { "id": "9c2e…", "role": "ASSISTANT", "status": "completed", "text": "The notice periods…", "parts": [] }
  ]
}

chat object. The same summary as in the conversation listing.
messages array of objects. The history in the order it happened. role is USER or ASSISTANT; the agent's answers also carry parts.

Example request

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

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

Deletes a conversation with its answers. An answer still being written is stopped first.

Parameters

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

Returns

The response is a 204 with an empty body. A nonexistent conversation returns a 404.

Example request

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`

Stops the answer the conversation is currently writing. A conversation that is not writing is left alone and its current state is returned.

Parameters

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

Returns

The response is a 202 with the conversation summary in the same shape as in the listing. The stop may still be settling, so status can still read in_progress.

Example request

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

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://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`

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