API v1 endpoints

For the extended interface, see REST API v2.

Base URL: https://vm.codexis.ai. All requests require the X-Api-Key header. Examples use the CODEXIS_API_KEY environment variable.

Authentication and HTTP errors.

Virtual machine

• GET /api/v1/vm
• POST /api/v1/vm/start
• POST /api/v1/vm/stop

Chat

• POST /api/v1/chats
• GET /api/v1/chats
• GET /api/v1/chats/{chatId}
• DELETE /api/v1/chats/{chatId}
• POST /api/v1/chats/{chatId}/stop
• GET /api/v1/chats/{chatId}/messages/{messageId}
• GET /api/v1/chats/{chatId}/messages/{messageId}/events
• GET /api/v1/chats/{chatId}/events
• GET /api/v1/models
• GET /api/v1/jurisdictions
• GET /api/v1/skills
• GET /api/v1/agents

Attachments

• POST /api/v1/attachments

Files

• POST /api/v1/files
• GET /api/v1/files/{path}
• DELETE /api/v1/files/{path}
• GET /api/v1/directories
• GET /api/v1/directories/{path}
• POST /api/v1/directories/{path}

Virtual machineCopy Anchor Link

The virtual machine must be RUNNING to process a request.

GET /api/v1/vmCopy Anchor Link

Returns virtual machine status.

ReturnsCopy Anchor Link

{ "status": "RUNNING" }

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

Example requestCopy Anchor Link

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

POST /api/v1/vm/startCopy Anchor Link

Starts the virtual machine.

ReturnsCopy Anchor Link

{ "status": "STARTING" }

202. Poll GET /api/v1/vm for RUNNING.

Example requestCopy Anchor Link

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

POST /api/v1/vm/stopCopy Anchor Link

Stops the virtual machine.

ReturnsCopy Anchor Link

{ "status": "STOPPING" }

202. Poll GET /api/v1/vm for STOPPED.

Example requestCopy Anchor Link

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

CatalogsCopy Anchor Link

Accept-Language: cs, en, sk. Default label language: cs.

GET /api/v1/modelsCopy Anchor Link

Lists models and their settings.

ReturnsCopy Anchor Link

[
  {
    "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,
    "disabled": false,
    "supportsWebSearch": true,
    "settings": [
      {
        "key": "reasoningEffort",
        "label": "Reasoning effort",
        "options": [
          { "value": "LOW", "label": "Low" },
          { "value": "MEDIUM", "label": "Medium" },
          { "value": "HIGH", "label": "High" }
        ],
        "defaultValue": "MEDIUM"
      }
    ]
  }
]

• id: value for model.
• provider: OPENAI, ANTHROPIC, GOOGLE, TENSOR_X, OPENROUTER, CODEXIS.
• status: provider health, UP, DEGRADED, DOWN, UNKNOWN.
• default: default model.
• disabled: model disabled for new questions.
• supportsWebSearch: supports webSearchEnabled.
• settings: accepted key and options[].value pairs. Empty for disabled models.

Example requestCopy Anchor Link

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

GET /api/v1/jurisdictionsCopy Anchor Link

Lists available jurisdictions.

ReturnsCopy Anchor Link

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

200. Pass the id values in jurisdictions.

Example requestCopy Anchor Link

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

GET /api/v1/skillsCopy Anchor Link

Lists skills, most used first.

ReturnsCopy Anchor Link

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

200. skillIds accepts id, name or fullName.

Example requestCopy Anchor Link

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

GET /api/v1/agentsCopy Anchor Link

Lists agents.

ReturnsCopy Anchor Link

200. Same structure as skills. agentId accepts id, name or fullName.

Example requestCopy Anchor Link

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

AttachmentsCopy Anchor Link

POST /api/v1/attachmentsCopy Anchor Link

Uploads message attachments.

ParametersCopy Anchor Link

multipart/form-data

• files file[], required, multipart. Repeat the field for each file. Files require a filename and non-empty content.

ReturnsCopy Anchor Link

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

201. An attachment array, including for a single file. size is in bytes, createdAt in ISO 8601. Pass the IDs as attachmentIds to POST /api/v1/chats.

Sending a message moves the attachment into the conversation and consumes its ID. Upload the file again to attach it to another message.

Example requestCopy Anchor Link

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

FilesCopy Anchor Link

All file endpoints require chatId in the query. Paths belong to that conversation workspace.

POST /api/v1/filesCopy Anchor Link

Uploads a file into a conversation.

ParametersCopy Anchor Link

multipart/form-data

• chatId string (UUID), required, query. Conversation identifier.
• file file, required, multipart. Non-empty file with a filename.
• destination string, optional, multipart. Existing target directory. Default: /home/codexis.

ReturnsCopy Anchor Link

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

201. Use path for downloads, deletes or in the question text with the same chatId. size is in bytes.

Example requestCopy Anchor Link

curl -X POST -F "file=@contract.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}Copy Anchor Link

Downloads a file.

ParametersCopy Anchor Link

• chatId string (UUID), required, query. Conversation identifier.
• path string, required, path. Path from an upload or directory listing. Preserve slashes; URL-encode other special characters.

ReturnsCopy Anchor Link

200. Binary stream with Content-Type, Content-Length and Content-Disposition headers.

Example requestCopy Anchor Link

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

GET /api/v1/directoriesCopy Anchor Link

Lists /home/codexis for the conversation.

ParametersCopy Anchor Link

• chatId string (UUID), required, query. Conversation identifier.

ReturnsCopy Anchor Link

200. Same format as a directory listing.

Example requestCopy Anchor Link

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}Copy Anchor Link

Lists one directory level, excluding hidden entries.

ParametersCopy Anchor Link

• chatId string (UUID), required, query. Conversation identifier.
• path string, required, path. Directory path in the conversation workspace.

ReturnsCopy Anchor Link

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

200. Use entries[].path with the same chatId. entries[].type: FILE, DIRECTORY, SYMLINK, OTHER.

Example requestCopy Anchor Link

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}Copy Anchor Link

Deletes a file or directory.

ParametersCopy Anchor Link

• chatId string (UUID), required, query. Conversation identifier.
• path string, required, path. Path from an upload or directory listing. Preserve slashes; URL-encode other special characters.
• recursive boolean, optional, query. Delete a directory with its contents. Default: false.

ReturnsCopy Anchor Link

204, empty body. Non-empty directories require recursive=true.

Example requestCopy Anchor Link

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

POST /api/v1/directories/{path}Copy Anchor Link

Creates a directory. The parent directory must exist.

ParametersCopy Anchor Link

• chatId string (UUID), required, query. Conversation identifier.
• path string, required, path. Directory path in the conversation workspace.

ReturnsCopy Anchor Link

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

201. Use path as an upload destination.

Example requestCopy Anchor Link

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

ConversationsCopy Anchor Link

POST /api/v1/chatsCopy Anchor Link

Sends a question.

ParametersCopy Anchor Link

application/json

• input string, required. Non-empty question text.
• chatId string (UUID), optional. Existing conversation; omit to create one. Existing conversations retain model, settings, jurisdictions and webSearchEnabled.
• agentId string, optional. id, name or fullName from GET /api/v1/agents. Default: the account’s default agent.
• skillIds string[], optional. id, name or fullName from GET /api/v1/skills.
• attachmentIds string[] (UUID), optional. Single-use IDs from POST /api/v1/attachments.
• model string, optional. id from GET /api/v1/models. Default: model with default: true. Unknown ID returns 400.
• jurisdictions string[], optional. id values from GET /api/v1/jurisdictions.
• webSearchEnabled boolean, optional. Requires supportsWebSearch: true on the model. Default: false.
• settings object[], optional. key and value pairs from settings in GET /api/v1/models.

ReturnsCopy Anchor Link

{
  "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 with status in_progress, or 201 with status completed.

• id: agent message UUID.
• chatId: conversation UUID for follow-up requests.
• text: current answer in Markdown. Citations are in parts.
• parts: structured answer parts.
• createdAt: ISO 8601.

Example requestCopy Anchor Link

curl -X POST -H "X-Api-Key: $CODEXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Check the notice periods in the attached contract.", "attachmentIds": ["62c96c7a-92f7-4b36-b1b8-6e124bc85502"]}' \
  https://vm.codexis.ai/api/v1/chats

Continue a conversationCopy Anchor Link

Send the same chatId to continue.

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

Lists conversations by most recent activity.

ParametersCopy Anchor Link

• offset integer, optional, query. Conversations to skip, minimum 0. Default: 0.
• limit integer, optional, query. Result count, 1 to 200. Default: 50.

ReturnsCopy Anchor Link

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

200. status: in_progress while generating, otherwise completed.

Example requestCopy Anchor Link

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

GET /api/v1/chats/{chatId}Copy Anchor Link

Returns a conversation and its messages in chronological order.

ParametersCopy Anchor Link

• chatId string (UUID), required, path. Conversation identifier.

ReturnsCopy Anchor Link

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

200. chat matches a conversation list item. messages[].role: USER or ASSISTANT; answers include parts.

Example requestCopy Anchor Link

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}Copy Anchor Link

Stops the active response and deletes the conversation and its messages.

ParametersCopy Anchor Link

• chatId string (UUID), required, path. Conversation identifier.

ReturnsCopy Anchor Link

204, empty body. Missing conversation: 404.

Example requestCopy Anchor Link

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}/stopCopy Anchor Link

Stops response generation. Completed conversations are unchanged.

ParametersCopy Anchor Link

• chatId string (UUID), required, path. Conversation identifier.

ReturnsCopy Anchor Link

202. Conversation summary; status may remain in_progress while stopping.

Example requestCopy Anchor Link

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}Copy Anchor Link

Returns the current answer state.

ParametersCopy Anchor Link

• chatId string (UUID), required, path. Conversation identifier.
• messageId string (UUID), required, path. The id returned by POST /api/v1/chats.

ReturnsCopy Anchor Link

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

200. Same object as POST /api/v1/chats, available while the conversation exists. Use SSE for updates.

Example requestCopy Anchor Link

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}/eventsCopy Anchor Link

SSE stream for one answer.

ParametersCopy Anchor Link

• chatId string (UUID), required, path. Conversation identifier.
• messageId string (UUID), required, path. The id returned by POST /api/v1/chats.

ReturnsCopy Anchor Link

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

200, text/event-stream. Each message event contains the current answer. The completed event closes the stream.

Example requestCopy Anchor Link

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}/eventsCopy Anchor Link

Conversation SSE stream. Stays open between requests.

ParametersCopy Anchor Link

• chatId string (UUID), required, path. Conversation identifier.

ReturnsCopy Anchor Link

200, text/event-stream. Events message and completed use the answer stream format for the latest answer in the conversation.

Example requestCopy Anchor Link

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

OpenAPI specificationCopy Anchor Link

openapi.yaml