Request and response schemas

This page defines the JSON objects used by the HTTP reference. Fields marked “optional” may be omitted; nullable fields also accept JSON null. Unknown request fields are currently ignored rather than rejected.

Core and account objects

Health = { status: "ok", version: string }
Error = { error: string, details?: string }
AccountUser = {
  id: string, email: string, display_name: string|null,
  avatar_url: string|null, connected_providers: string[]
}
AccountSession = { authenticated: boolean, user: AccountUser|null, notice?: string }
AccountLogin = { email: nonblank string, password: nonblank string }
SignupCodeRequest = { email: nonblank string }
SignupCompleteRequest = {
  email: nonblank string, code: nonblank string, password: nonblank string,
  display_name?: string
}

Account input is trimmed, including passwords and verification codes. Account fields are snake_case; this differs from most resource DTOs.

Workspace, thread, and message objects

Workspace = {
  id: integer, uuid: string, name: string, description: string|null,
  defaultModelId: string|null, toolsConfig: string|null,
  directories: string|null, approvalConfig: string|null, ragConfig: string|null,
  createdAt: ISO datetime, updatedAt: ISO datetime
}
CreateWorkspace = {
  name: string(min length 1), description?: string|null,
  defaultModelId?: string|null, toolsConfig?: string|null,
  directories?: string|null, approvalConfig?: string|null, ragConfig?: string|null
}
Thread = {
  id: integer, uuid: string, workspaceUuid: string, title: string|null,
  description: string|null, defaultModelId: string|null,
  toolsConfig: string|null, createdAt: ISO datetime, updatedAt: ISO datetime
}
CreateThread = {
  workspaceUuid: string, title?: string|null, description?: string|null,
  defaultModelId?: string|null, toolsConfig?: string|null
}
UpdateThread = {
  title?: string|null, description?: string|null,
  defaultModelId?: string|null, toolsConfig?: string|null
}
Message = {
  uuid: string, threadUuid: string,
  role: "user"|"assistant"|"system"|"tool",
  content: string, createdAt: ISO datetime
}
CreateMessage = { threadUuid: string, role: Message.role, content: string }

directories, toolsConfig, approvalConfig, and ragConfig are JSON encoded as strings, not nested objects. Workspace CRUD stores them without validating the embedded JSON; file, RAG, and chat operations validate or parse them when used.

Embedded workspace policy JSON

{
  "directories": "[\"C:\\\\code\\\\project\"]",
  "toolsConfig": "{\"builtin_enabled\":true,\"builtin\":{\"filesystem\":{\"enabled\":false}}}",
  "approvalConfig": "{\"create\":true,\"read\":false,\"update\":true,\"delete\":true}",
  "ragConfig": "{\"roots\":[{\"path\":\"C:\\\\code\\\\project\",\"enabled\":true}]}"
}

See Workspaces and threads for inheritance and lifecycle semantics.

File objects

FileSearchMatch = { rootIndex: integer, name: string, relativePath: string }
FileEntry = { name: string, relativePath: string, isDirectory: boolean }
FileContent = { content: string }
MovePath = {
  sourceRootIndex: integer, sourcePath: string,
  destinationRootIndex: integer, destinationPath: string
}

For preview responses, the body is raw bytes rather than JSON. Content-Type is validated from the extension; Content-Disposition is inline; Content-Length, Cache-Control: no-store, private, X-Content-Type-Options: nosniff, and X-Preview-Kind: image|pdf|docx are set.

Text content extensions are .c, .cc, .cpp, .cs, .csx, .css, .fs, .fsx, .go, .h, .hpp, .html, .htm, .java, .js, .jsx, .json, .md, .markdown, .php, .ps1, .py, .rb, .rs, .sh, .sql, .toml, .ts, .tsx, .txt, .xml, .xaml, .yml, and .yaml.

Settings

Setting = { key: string, value: string, tag: string|null, client: string|null }

PUT /settings requires a non-empty array, a nonblank key, and unique exact (key,tag,client) tuples within the request. Values are strings and are not normalized.

Model objects

ModelConfiguration = {
  id: string, provider: string, model: string, alias: string|null,
  baseUrl: string|null, region: string|null, contextWindow: integer|null,
  hasApiKey: boolean
}
UpsertModelConfiguration = {
  provider: nonblank string, model: nonblank string,
  alias?: string|null, baseUrl?: string|null, region?: string|null,
  contextWindow?: positive integer|null, apiKey?: string|null,
  awsAccessKeyId?: string|null, awsSecretAccessKey?: string|null,
  awsSessionToken?: string|null, clearApiKey?: boolean=false
}
Model = { id: string, name: string, provider: string, description: string|null }
ProblemDetails = {
  type: "about:blank",
  title: "Encrypted credential storage is unavailable.",
  status: 503, detail: string
}

On model update, provider and model remain required. Omitted alias/base URL/region/context window are cleared. For apiKey and every AWS credential, explicit null is treated like omission and preserves the stored value. clearApiKey:true clears the API key only when apiKey is null or omitted; any non-null apiKey, including an empty string, takes precedence. There is no dedicated AWS-credential clear flag.

Tool objects

BuiltinTool = {
  name: string, doc: string,
  operation: "create"|"read"|"update"|"delete"
}
ToolCatalog = {
  builtin: { [group: string]: BuiltinTool[] },
  configured: ToolConfiguration[]
}
ToolConfiguration = {
  id: integer, uuid: string, name: string, alias: string|null,
  description: string|null, toolType: "script"|"api"|"mcp",
  scriptPath: string|null, scriptLanguage: string|null,
  endpointUrl: string|null, authType: string|null,
  hasAuthConfig: boolean, status: string,
  createdAt: ISO datetime, updatedAt: ISO datetime
}
UpsertToolConfiguration = {
  name?: string|null, alias?: string|null, description?: string|null,
  toolType?: "script"|"api"|"mcp"|null,
  scriptPath?: string|null, scriptLanguage?: string|null,
  endpointUrl?: string|null, authType?: "api_key"|null,
  authConfigJson?: string|null, clearAuthConfig?: boolean=false,
  status?: string|null
}

Create defaults toolType to script and status to active; alias or name is required. Endpoint URLs are allowed only for API/MCP tools and must be HTTP(S) without embedded credentials. authConfigJson is a JSON-encoded non-empty object of unique valid HTTP header names to nonblank CR/LF-free strings, and requires API/MCP type plus api_key auth.

Tool update preserves an omitted name, alias fallback, tool type, and status. It clears omitted description/script path/language/endpoint. Omitting authType removes existing API-key auth, even when clearAuthConfig is false.

Retrieval objects

RagSearch = {
  query: string(min length 1),
  mode?: "keyword"|"vector"|"hybrid" = "hybrid",
  limit?: integer(1..50) = 8
}
RagRootIndex = {
  rootIndex: integer, indexed: integer, unchanged: integer,
  skipped: integer, errors: integer, removed: integer
}
RagWorkspaceIndex = { roots: RagRootIndex[] }
RagResult = {
  chunk_id: integer, document_id: integer, path: string,
  document_path: string, ordinal: integer, content: string,
  start_line: integer|null, end_line: integer|null,
  token_estimate: integer|null, status: string, score: number,
  result_type: "chunk", rootIndex: integer,
  keyword_score?: number, vector_score?: number,
  sensitive?: true, metadata_only?: true
}

Whitespace-only queries pass the schema but may produce no results. Hybrid results include component scores. Sensitive paths replace content with a safe existence notice and null line ranges.

Status-code details

• Workspace, thread, and message creates return 200, not 201.
• Model and configured-tool creates return 201 with Location.
• Deletes return an empty 204; absent model/tool deletes use an empty 404 rather than an Error object.
• Unknown workspace thread-list and unknown thread message-list requests return 200 [].
• Unexpected framework/database/model failures have no stable public error schema and may return 500.