openapi: 3.0.0 info: title: Dexto API version: 1.7.1 description: OpenAPI spec for the Dexto REST API server servers: - url: http://localhost:3001 description: Local development server (default port) - url: http://localhost:{port} description: Local development server (custom port) variables: port: default: '3001' description: API server port tags: - name: system description: System health and status endpoints - name: config description: Agent configuration and greeting management - name: messages description: Send messages to the agent and manage conversations - name: sessions description: Create and manage conversation sessions - name: schedules description: Create and manage automation schedules - name: llm description: Configure and switch between LLM providers and models - name: mcp description: Manage Model Context Protocol (MCP) servers and tools - name: webhooks description: Register and manage webhook endpoints for agent events - name: search description: Search through messages and sessions - name: memory description: Store and retrieve agent memories for context - name: prompts description: Manage custom prompts and templates - name: resources description: Access and manage resources from MCP servers and internal providers - name: agent description: Current agent configuration and file operations - name: agents description: Install, switch, and manage agent configurations - name: queue description: Manage message queue for busy sessions - name: openrouter description: OpenRouter model validation and cache management - name: discovery description: Discover available providers and capabilities - name: tools description: List and inspect available tools from local and MCP sources - name: models description: List and manage local GGUF models and Ollama models - name: auth description: Dexto authentication status and management components: schemas: JsonObject: type: object description: JSON object with arbitrary serializable values additionalProperties: $ref: '#/components/schemas/JsonValue' JsonValue: anyOf: - type: string - type: number - type: boolean - type: array items: $ref: '#/components/schemas/JsonValue' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' nullable: true description: Any JSON-serializable value parameters: {} paths: /health: get: summary: Health Check description: Returns server health status tags: - system responses: '200': description: Server health content: text/plain: schema: type: string example: OK /v1/message:send: post: summary: Send Message description: Send a message to the agent (A2A message/send) tags: - a2a requestBody: content: application/json: schema: type: object properties: message: type: object properties: role: type: string enum: - user - agent description: Message role parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Message parts messageId: type: string description: Unique message identifier taskId: type: string description: Associated task ID contextId: type: string description: Context identifier metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers referenceTaskIds: type: array items: type: string description: Referenced task IDs kind: type: string enum: - message description: Object type discriminator required: - role - parts - messageId - kind description: Message to send to the agent configuration: type: object properties: acceptedOutputModes: type: array items: type: string description: Accepted output MIME types historyLength: type: number description: Limit conversation history length pushNotificationConfig: type: object properties: url: type: string description: Push notification webhook URL headers: type: object additionalProperties: type: string description: HTTP headers for webhook required: - url description: Push notification configuration blocking: type: boolean description: Wait for task completion description: Optional configuration metadata: type: object additionalProperties: true description: Optional metadata required: - message description: Request body for message/send responses: '200': description: Task with agent response content: application/json: schema: type: object properties: id: type: string description: Unique task identifier contextId: type: string description: Context identifier across related tasks status: type: object properties: state: type: string enum: - submitted - working - input-required - completed - canceled - failed - rejected - auth-required - unknown description: Current task state message: type: object properties: role: type: string enum: - user - agent description: Message role parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Message parts messageId: type: string description: Unique message identifier taskId: type: string description: Associated task ID contextId: type: string description: Context identifier metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers referenceTaskIds: type: array items: type: string description: Referenced task IDs kind: type: string enum: - message description: Object type discriminator required: - role - parts - messageId - kind description: Status message timestamp: type: string description: ISO 8601 timestamp required: - state description: Current task status history: type: array items: type: object properties: role: type: string enum: - user - agent description: Message role parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Message parts messageId: type: string description: Unique message identifier taskId: type: string description: Associated task ID contextId: type: string description: Context identifier metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers referenceTaskIds: type: array items: type: string description: Referenced task IDs kind: type: string enum: - message description: Object type discriminator required: - role - parts - messageId - kind description: A2A Protocol message description: Conversation history artifacts: type: array items: type: object properties: artifactId: type: string description: Unique artifact ID name: type: string description: Artifact name description: type: string description: Artifact description parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Artifact content parts metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers required: - artifactId - parts description: A2A protocol artifact description: Task artifacts metadata: type: object additionalProperties: true description: Extension metadata kind: type: string enum: - task description: Object type discriminator required: - id - contextId - status - kind description: A2A Protocol task '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /v1/tasks: get: summary: List Tasks description: List all A2A tasks with optional filtering (A2A tasks/list) tags: - a2a parameters: - schema: type: string description: Filter by context ID required: false description: Filter by context ID name: contextId in: query - schema: type: string enum: - submitted - working - input-required - completed - canceled - failed - rejected - auth-required - unknown description: Filter by task state required: false description: Filter by task state name: status in: query - schema: type: string description: Number of results (1-100, default 50) required: false description: Number of results (1-100, default 50) name: pageSize in: query - schema: type: string description: Pagination token (not yet implemented - reserved for future use) required: false description: Pagination token (not yet implemented - reserved for future use) name: pageToken in: query - schema: type: string description: >- Limit history items (not yet implemented - reserved for future use) required: false description: Limit history items (not yet implemented - reserved for future use) name: historyLength in: query - schema: type: string description: >- Unix timestamp filter (not yet implemented - reserved for future use) required: false description: >- Unix timestamp filter (not yet implemented - reserved for future use) name: lastUpdatedAfter in: query - schema: type: string description: >- Include artifacts in response (not yet implemented - reserved for future use) required: false description: >- Include artifacts in response (not yet implemented - reserved for future use) name: includeArtifacts in: query responses: '200': description: Task list content: application/json: schema: type: object properties: tasks: type: array items: type: object properties: id: type: string description: Unique task identifier contextId: type: string description: Context identifier across related tasks status: type: object properties: state: type: string enum: - submitted - working - input-required - completed - canceled - failed - rejected - auth-required - unknown description: Current task state message: type: object properties: role: type: string enum: - user - agent description: Message role parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Message parts messageId: type: string description: Unique message identifier taskId: type: string description: Associated task ID contextId: type: string description: Context identifier metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers referenceTaskIds: type: array items: type: string description: Referenced task IDs kind: type: string enum: - message description: Object type discriminator required: - role - parts - messageId - kind description: Status message timestamp: type: string description: ISO 8601 timestamp required: - state description: Current task status history: type: array items: type: object properties: role: type: string enum: - user - agent description: Message role parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Message parts messageId: type: string description: Unique message identifier taskId: type: string description: Associated task ID contextId: type: string description: Context identifier metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers referenceTaskIds: type: array items: type: string description: Referenced task IDs kind: type: string enum: - message description: Object type discriminator required: - role - parts - messageId - kind description: A2A Protocol message description: Conversation history artifacts: type: array items: type: object properties: artifactId: type: string description: Unique artifact ID name: type: string description: Artifact name description: type: string description: Artifact description parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Artifact content parts metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers required: - artifactId - parts description: A2A protocol artifact description: Task artifacts metadata: type: object additionalProperties: true description: Extension metadata kind: type: string enum: - task description: Object type discriminator required: - id - contextId - status - kind description: A2A Protocol task description: Array of tasks totalSize: type: number description: Total number of tasks pageSize: type: number description: Number of tasks in this page nextPageToken: type: string description: Token for next page required: - tasks - totalSize - pageSize - nextPageToken description: Response body for tasks/list '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /v1/tasks/{id}: get: summary: Get Task description: Retrieve a specific task by ID (A2A tasks/get) tags: - a2a parameters: - schema: type: string description: Task ID required: true description: Task ID name: id in: path responses: '200': description: Task details content: application/json: schema: type: object properties: id: type: string description: Unique task identifier contextId: type: string description: Context identifier across related tasks status: type: object properties: state: type: string enum: - submitted - working - input-required - completed - canceled - failed - rejected - auth-required - unknown description: Current task state message: type: object properties: role: type: string enum: - user - agent description: Message role parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Message parts messageId: type: string description: Unique message identifier taskId: type: string description: Associated task ID contextId: type: string description: Context identifier metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers referenceTaskIds: type: array items: type: string description: Referenced task IDs kind: type: string enum: - message description: Object type discriminator required: - role - parts - messageId - kind description: Status message timestamp: type: string description: ISO 8601 timestamp required: - state description: Current task status history: type: array items: type: object properties: role: type: string enum: - user - agent description: Message role parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Message parts messageId: type: string description: Unique message identifier taskId: type: string description: Associated task ID contextId: type: string description: Context identifier metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers referenceTaskIds: type: array items: type: string description: Referenced task IDs kind: type: string enum: - message description: Object type discriminator required: - role - parts - messageId - kind description: A2A Protocol message description: Conversation history artifacts: type: array items: type: object properties: artifactId: type: string description: Unique artifact ID name: type: string description: Artifact name description: type: string description: Artifact description parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Artifact content parts metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers required: - artifactId - parts description: A2A protocol artifact description: Task artifacts metadata: type: object additionalProperties: true description: Extension metadata kind: type: string enum: - task description: Object type discriminator required: - id - contextId - status - kind description: A2A Protocol task '404': description: Task not found content: application/json: schema: type: object properties: error: type: string description: Task error message required: - error additionalProperties: false description: A2A task error response /v1/tasks/{id}:cancel: post: summary: Cancel Task description: Cancel a running task (A2A tasks/cancel) tags: - a2a parameters: - schema: type: string description: Task ID required: true description: Task ID name: id in: path responses: '200': description: Task cancelled content: application/json: schema: type: object properties: id: type: string description: Unique task identifier contextId: type: string description: Context identifier across related tasks status: type: object properties: state: type: string enum: - submitted - working - input-required - completed - canceled - failed - rejected - auth-required - unknown description: Current task state message: type: object properties: role: type: string enum: - user - agent description: Message role parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Message parts messageId: type: string description: Unique message identifier taskId: type: string description: Associated task ID contextId: type: string description: Context identifier metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers referenceTaskIds: type: array items: type: string description: Referenced task IDs kind: type: string enum: - message description: Object type discriminator required: - role - parts - messageId - kind description: Status message timestamp: type: string description: ISO 8601 timestamp required: - state description: Current task status history: type: array items: type: object properties: role: type: string enum: - user - agent description: Message role parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Message parts messageId: type: string description: Unique message identifier taskId: type: string description: Associated task ID contextId: type: string description: Context identifier metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers referenceTaskIds: type: array items: type: string description: Referenced task IDs kind: type: string enum: - message description: Object type discriminator required: - role - parts - messageId - kind description: A2A Protocol message description: Conversation history artifacts: type: array items: type: object properties: artifactId: type: string description: Unique artifact ID name: type: string description: Artifact name description: type: string description: Artifact description parts: type: array items: oneOf: - type: object properties: kind: type: string enum: - text description: Part type discriminator text: type: string description: Text content metadata: type: object additionalProperties: true description: Extension metadata required: - kind - text - type: object properties: kind: type: string enum: - file description: Part type discriminator file: anyOf: - type: object properties: bytes: type: string description: Base64-encoded file data name: type: string description: File name mimeType: type: string description: MIME type required: - bytes - type: object properties: uri: type: string description: File URI name: type: string description: File name mimeType: type: string description: MIME type required: - uri description: File data (bytes or URI) metadata: type: object additionalProperties: true description: Extension metadata required: - kind - file - type: object properties: kind: type: string enum: - data description: Part type discriminator data: $ref: '#/components/schemas/JsonObject' metadata: type: object additionalProperties: true description: Extension metadata required: - kind - data description: Message part (text, file, or data) description: Artifact content parts metadata: type: object additionalProperties: true description: Extension metadata extensions: type: array items: type: string description: Extension identifiers required: - artifactId - parts description: A2A protocol artifact description: Task artifacts metadata: type: object additionalProperties: true description: Extension metadata kind: type: string enum: - task description: Object type discriminator required: - id - contextId - status - kind description: A2A Protocol task '404': description: Task not found content: application/json: schema: type: object properties: error: type: string description: Task error message required: - error additionalProperties: false description: A2A task error response /api/greeting: get: summary: Get Greeting Message description: Retrieves the greeting message from the agent configuration tags: - config parameters: - schema: type: string description: Session identifier to retrieve session-specific greeting required: false description: Session identifier to retrieve session-specific greeting name: sessionId in: query responses: '200': description: Greeting content: application/json: schema: type: object properties: greeting: type: string description: Greeting message from agent configuration additionalProperties: false description: Greeting response payload '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/message: post: summary: Send Message (async) description: >- Sends a message and returns immediately. The full response will be sent over SSE tags: - messages requestBody: content: application/json: schema: type: object properties: content: anyOf: - type: string - type: array items: oneOf: - type: object properties: type: type: string enum: - text description: 'Part type: text' text: type: string description: Text content required: - type - text additionalProperties: false description: Text content part - type: object properties: type: type: string enum: - image description: 'Part type: image' image: type: string description: Base64-encoded image data mimeType: type: string description: MIME type of the image required: - type - image additionalProperties: false description: Image content part - type: object properties: type: type: string enum: - file description: 'Part type: file' data: type: string description: Base64-encoded file data mimeType: type: string description: MIME type of the file filename: type: string description: Optional filename required: - type - data - mimeType additionalProperties: false description: File content part description: Request message content part (text, image, or file) description: >- Message content - string for text, or ContentPart[] for multimodal sessionId: type: string minLength: 1 description: The session to use for this message required: - content - sessionId description: Request body for sending a message to the agent responses: '202': description: Message accepted for async processing; subscribe to SSE for results content: application/json: schema: type: object properties: accepted: type: boolean enum: - true description: Indicates request was accepted sessionId: type: string description: Session ID used for this message required: - accepted - sessionId additionalProperties: false description: Asynchronous message acceptance response '400': description: Validation error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/message-sync: post: summary: Send Message (sync) description: Sends a message and waits for the full response tags: - messages requestBody: content: application/json: schema: type: object properties: content: anyOf: - type: string - type: array items: oneOf: - type: object properties: type: type: string enum: - text description: 'Part type: text' text: type: string description: Text content required: - type - text additionalProperties: false description: Text content part - type: object properties: type: type: string enum: - image description: 'Part type: image' image: type: string description: Base64-encoded image data mimeType: type: string description: MIME type of the image required: - type - image additionalProperties: false description: Image content part - type: object properties: type: type: string enum: - file description: 'Part type: file' data: type: string description: Base64-encoded file data mimeType: type: string description: MIME type of the file filename: type: string description: Optional filename required: - type - data - mimeType additionalProperties: false description: File content part description: Request message content part (text, image, or file) description: >- Message content - string for text, or ContentPart[] for multimodal sessionId: type: string minLength: 1 description: The session to use for this message required: - content - sessionId description: Request body for sending a message to the agent responses: '200': description: Synchronous response content: application/json: schema: type: object properties: response: type: string description: Agent response text sessionId: type: string description: Session ID used for this message tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used additionalProperties: false description: Token usage statistics messageId: type: string format: uuid description: Assistant message ID for this response usageScopeId: type: string description: >- Optional usage scope identifier for runtime-scoped metering estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this response pricingStatus: type: string enum: - estimated - unpriced description: Whether pricing was resolved for this response reasoning: type: string description: Extended thinking content from reasoning models model: type: string description: Model used for this response provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider hostRuntime: type: object properties: ids: type: object additionalProperties: type: string minLength: 1 description: >- Optional host-owned runtime IDs used for correlation across orchestration, telemetry, logs, and events. additionalProperties: false description: Host-owned runtime IDs surfaced by core runtime flows required: - response - sessionId additionalProperties: false description: Synchronous message response '400': description: Validation error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/reset: post: summary: Reset Conversation description: Resets the conversation history for a given session tags: - messages requestBody: content: application/json: schema: type: object properties: sessionId: type: string minLength: 1 description: The ID of the session to reset required: - sessionId description: Request body for resetting a conversation responses: '200': description: Reset initiated content: application/json: schema: type: object properties: status: type: string description: Status message indicating reset was initiated sessionId: type: string description: Session ID that was reset required: - status - sessionId additionalProperties: false description: Session reset response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/message-stream: post: summary: Stream message response description: >- Sends a message and streams the response via Server-Sent Events (SSE). Returns SSE stream directly in response. Events include llm:thinking, llm:chunk, llm:tool-call, llm:tool-result, llm:response, and llm:error. Final llm:response events include token usage, assistant message ID, and pricing metadata when available. If the session is busy processing another message, returns 202 with queue information. tags: - messages requestBody: content: application/json: schema: type: object properties: content: anyOf: - type: string - type: array items: oneOf: - type: object properties: type: type: string enum: - text description: 'Part type: text' text: type: string description: Text content required: - type - text additionalProperties: false description: Text content part - type: object properties: type: type: string enum: - image description: 'Part type: image' image: type: string description: Base64-encoded image data mimeType: type: string description: MIME type of the image required: - type - image additionalProperties: false description: Image content part - type: object properties: type: type: string enum: - file description: 'Part type: file' data: type: string description: Base64-encoded file data mimeType: type: string description: MIME type of the file filename: type: string description: Optional filename required: - type - data - mimeType additionalProperties: false description: File content part description: Request message content part (text, image, or file) description: >- Message content - string for text, or ContentPart[] for multimodal sessionId: type: string minLength: 1 description: The session to use for this message required: - content - sessionId description: Request body for sending a message to the agent responses: '200': description: >- SSE stream of agent events. Standard SSE format with event type and JSON data. headers: Content-Type: description: SSE content type schema: type: string example: text/event-stream Cache-Control: description: Disable caching for stream schema: type: string example: no-cache Connection: description: Keep connection alive for streaming schema: type: string example: keep-alive X-Accel-Buffering: description: Disable nginx buffering schema: type: string example: 'no' content: text/event-stream: schema: type: string description: >- Server-Sent Events stream. Events: llm:thinking (start), llm:chunk (text fragments), llm:tool-call (tool execution), llm:tool-result (tool output), llm:response (final), llm:error (errors). Final llm:response payloads include token usage, assistant message ID, and pricing metadata when available. '202': description: >- Session is busy processing another message. Use the queue endpoints to manage pending messages. content: application/json: schema: type: object properties: busy: type: boolean enum: - true description: Indicates session is busy sessionId: type: string description: The session ID queueLength: type: number description: Current number of messages in queue hint: type: string description: Instructions for the client required: - busy - sessionId - queueLength - hint additionalProperties: false description: Busy response for streaming requests '400': description: Validation error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/llm/current: get: summary: Get Current LLM Config description: >- Retrieves the current LLM configuration for the agent or a specific session tags: - llm parameters: - schema: type: string description: Session identifier to retrieve session-specific LLM configuration required: false description: Session identifier to retrieve session-specific LLM configuration name: sessionId in: query responses: '200': description: Current LLM config content: application/json: schema: type: object properties: config: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: >- LLM provider (e.g., 'openai', 'anthropic', 'google', 'groq') model: type: string description: Specific model name for the selected provider maxIterations: type: integer minimum: 0 exclusiveMinimum: true description: Max outer-loop tool-call iterations per agent turn baseURL: type: string description: >- Base URL for provider (e.g., https://api.openai.com/v1). Only certain providers support this. maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: >- Max input tokens for history; required for unknown models maxOutputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Max tokens for model output temperature: type: number nullable: true minimum: 0 maximum: 1 description: 'Randomness: 0 deterministic, 1 creative' allowedMediaTypes: type: array items: type: string description: >- MIME type patterns for media expansion (e.g., "image/*", "application/pdf"). If omitted, uses model capabilities from registry. Supports wildcards. reasoning: type: object properties: variant: type: string description: >- Model/provider-native reasoning variant (resolved by reasoning profile for the selected model). budgetTokens: type: integer minimum: 0 exclusiveMinimum: true description: >- Advanced escape hatch for budget-based providers (e.g., Anthropic/Gemini/Bedrock/OpenRouter). required: - variant additionalProperties: false description: >- Reasoning configuration using model/provider-native variants (tuning only; display is controlled separately). hasApiKey: type: boolean description: Whether an API key is configured displayName: type: string description: Human-readable model display name required: - provider - model additionalProperties: false routing: type: object properties: viaDexto: type: boolean description: Whether requests route through Dexto gateway required: - viaDexto description: Routing information for the current LLM configuration required: - config - routing description: Response containing current LLM configuration '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/llm/catalog: get: summary: LLM Catalog description: Providers, models, capabilities, and API key status tags: - llm parameters: - schema: type: string enum: - curated - all default: all description: >- Catalog scope: 'curated' returns a small, UI-friendly set of models; 'all' returns the full registry (can be large) required: false description: >- Catalog scope: 'curated' returns a small, UI-friendly set of models; 'all' returns the full registry (can be large) name: scope in: query - schema: anyOf: - type: string - type: array items: type: string description: Comma-separated list of LLM providers to filter by required: false description: Comma-separated list of LLM providers to filter by name: provider in: query - schema: anyOf: - type: string enum: - 'true' - type: string enum: - 'false' - type: string enum: - '1' - type: string enum: - '0' description: Include models list in the response (true or false) required: false description: Include models list in the response (true or false) name: includeModels in: query - schema: anyOf: - type: string enum: - 'true' - type: string enum: - 'false' - type: string enum: - '1' - type: string enum: - '0' description: Filter by API key presence (true or false) required: false description: Filter by API key presence (true or false) name: hasKey in: query - schema: type: string enum: - pdf - image - audio - video - document description: >- Filter by supported file type (audio, pdf, image, video, or document) required: false description: >- Filter by supported file type (audio, pdf, image, video, or document) name: fileType in: query - schema: anyOf: - type: string enum: - 'true' - type: string enum: - 'false' - type: string enum: - '1' - type: string enum: - '0' description: Include only default models (true or false) required: false description: Include only default models (true or false) name: defaultOnly in: query - schema: type: string enum: - grouped - flat default: grouped description: Response format mode (grouped by provider or flat list) required: false description: Response format mode (grouped by provider or flat list) name: mode in: query responses: '200': description: LLM catalog content: application/json: schema: anyOf: - type: object properties: providers: type: object properties: openai: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities openai-compatible: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities anthropic: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities google: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities groq: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities xai: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities cohere: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities minimax: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities glm: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities openrouter: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities litellm: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities glama: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities vertex: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities bedrock: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities local: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities ollama: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities dexto-nova: type: object properties: name: type: string description: Provider display name hasApiKey: type: boolean description: Whether API key is configured primaryEnvVar: type: string description: Primary environment variable for API key supportsBaseURL: type: boolean description: Whether custom base URLs are supported models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: >- Pricing information in USD per million tokens required: - name - maxInputTokens - supportedFileTypes additionalProperties: false description: Model information from LLM registry description: Models available from this provider supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: Provider-level file type support required: - name - hasApiKey - primaryEnvVar - supportsBaseURL - models - supportedFileTypes additionalProperties: false description: >- Provider catalog entry with models and capabilities description: >- Providers grouped by ID with their models and capabilities required: - providers additionalProperties: false description: Grouped catalog response (mode=grouped) - type: object properties: models: type: array items: type: object properties: name: type: string description: Model name identifier maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Maximum input tokens default: type: boolean description: Whether this is a default model supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types this model supports displayName: type: string description: Human-readable display name pricing: type: object properties: inputPerM: type: number description: Input cost per million tokens (USD) outputPerM: type: number description: Output cost per million tokens (USD) cacheReadPerM: type: number description: Cache read cost per million tokens cacheWritePerM: type: number description: Cache write cost per million tokens currency: type: string enum: - USD description: Currency unit: type: string enum: - per_million_tokens description: Unit required: - inputPerM - outputPerM description: Pricing information in USD per million tokens provider: type: string description: Provider identifier for this model required: - name - maxInputTokens - supportedFileTypes - provider additionalProperties: false description: Flattened model entry with provider information description: Flat list of all models with provider information required: - models additionalProperties: false description: Flat catalog response (mode=flat) description: >- LLM catalog in grouped or flat format based on mode query parameter '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/llm/switch: post: summary: Switch LLM description: Switches the LLM configuration for the agent or a specific session tags: - llm requestBody: content: application/json: schema: allOf: - type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: >- LLM provider (e.g., 'openai', 'anthropic', 'google', 'groq') model: type: string description: Specific model name for the selected provider apiKey: type: string description: >- API key for provider; can be given directly or via $ENV reference maxIterations: type: integer minimum: 0 exclusiveMinimum: true description: Max iterations for agentic loops baseURL: type: string description: >- Base URL for provider (e.g., https://api.openai.com/v1). Only certain providers support this. maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: >- Max input tokens for history; required for unknown models maxOutputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Max tokens for model output temperature: type: number nullable: true minimum: 0 maximum: 1 description: 'Randomness: 0 deterministic, 1 creative' allowedMediaTypes: type: array items: type: string description: >- MIME type patterns for media expansion (e.g., "image/*", "application/pdf"). If omitted, uses model capabilities from registry. Supports wildcards. reasoning: type: object nullable: true properties: variant: type: string description: >- Model/provider-native reasoning variant (resolved by reasoning profile for the selected model). budgetTokens: type: integer minimum: 0 exclusiveMinimum: true description: >- Advanced escape hatch for budget-based providers (e.g., Anthropic/Gemini/Bedrock/OpenRouter). required: - variant additionalProperties: false description: >- Reasoning configuration using model/provider-native variants (tuning only; display is controlled separately). - type: object properties: sessionId: type: string description: >- Session identifier for session-specific LLM configuration description: LLM switch request body with optional session ID and LLM fields responses: '200': description: LLM switch result content: application/json: schema: type: object properties: config: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: >- LLM provider (e.g., 'openai', 'anthropic', 'google', 'groq') model: type: string description: Specific model name for the selected provider maxIterations: type: integer minimum: 0 exclusiveMinimum: true description: Max outer-loop tool-call iterations per agent turn baseURL: type: string description: >- Base URL for provider (e.g., https://api.openai.com/v1). Only certain providers support this. maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true description: >- Max input tokens for history; required for unknown models maxOutputTokens: type: integer minimum: 0 exclusiveMinimum: true description: Max tokens for model output temperature: type: number nullable: true minimum: 0 maximum: 1 description: 'Randomness: 0 deterministic, 1 creative' allowedMediaTypes: type: array items: type: string description: >- MIME type patterns for media expansion (e.g., "image/*", "application/pdf"). If omitted, uses model capabilities from registry. Supports wildcards. reasoning: type: object properties: variant: type: string description: >- Model/provider-native reasoning variant (resolved by reasoning profile for the selected model). budgetTokens: type: integer minimum: 0 exclusiveMinimum: true description: >- Advanced escape hatch for budget-based providers (e.g., Anthropic/Gemini/Bedrock/OpenRouter). required: - variant additionalProperties: false description: >- Reasoning configuration using model/provider-native variants (tuning only; display is controlled separately). hasApiKey: type: boolean description: Whether an API key is configured required: - provider - model additionalProperties: false description: >- New LLM configuration with all defaults applied (apiKey omitted) sessionId: type: string description: Session ID if session-specific switch required: - config description: LLM switch result '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/llm/custom-models: get: summary: List Custom Models description: Returns all saved custom openai-compatible model configurations tags: - llm responses: '200': description: List of custom models content: application/json: schema: type: object properties: models: type: array items: type: object properties: name: type: string minLength: 1 provider: type: string enum: - openai-compatible - openrouter - litellm - glama - bedrock - ollama - local - vertex - dexto-nova default: openai-compatible baseURL: type: string format: uri displayName: type: string maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true maxOutputTokens: type: integer minimum: 0 exclusiveMinimum: true apiKey: type: string filePath: type: string reasoning: type: object properties: variant: type: string minLength: 1 budgetTokens: type: integer minimum: 0 exclusiveMinimum: true required: - variant additionalProperties: false required: - name description: List of custom models required: - models '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response post: summary: Create Custom Model description: Saves a new custom openai-compatible model configuration tags: - llm requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 provider: type: string enum: - openai-compatible - openrouter - litellm - glama - bedrock - ollama - local - vertex - dexto-nova default: openai-compatible baseURL: type: string format: uri displayName: type: string maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true maxOutputTokens: type: integer minimum: 0 exclusiveMinimum: true apiKey: type: string filePath: type: string reasoning: type: object properties: variant: type: string minLength: 1 budgetTokens: type: integer minimum: 0 exclusiveMinimum: true required: - variant additionalProperties: false required: - name responses: '200': description: Custom model saved content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Success indicator model: type: object properties: name: type: string minLength: 1 provider: type: string enum: - openai-compatible - openrouter - litellm - glama - bedrock - ollama - local - vertex - dexto-nova default: openai-compatible baseURL: type: string format: uri displayName: type: string maxInputTokens: type: integer minimum: 0 exclusiveMinimum: true maxOutputTokens: type: integer minimum: 0 exclusiveMinimum: true apiKey: type: string filePath: type: string reasoning: type: object properties: variant: type: string minLength: 1 budgetTokens: type: integer minimum: 0 exclusiveMinimum: true required: - variant additionalProperties: false required: - name required: - ok - model '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/llm/custom-models/{name}: delete: summary: Delete Custom Model description: Deletes a custom model by name tags: - llm parameters: - schema: type: string minLength: 1 description: Model name to delete required: true description: Model name to delete name: name in: path responses: '200': description: Custom model deleted content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Success indicator deleted: type: string description: Name of the deleted model required: - ok - deleted '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/llm/model-picker-state: get: summary: Model Picker State description: >- Returns hydrated Featured, Recents, Favorites, and Custom sections for the model picker. tags: - llm responses: '200': description: Hydrated model picker sections content: application/json: schema: type: object properties: featured: type: array items: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider model: type: string description: Model ID baseURL: type: string format: uri description: Variant-specific base URL displayName: type: string description: Human-readable model name supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types supported by this model source: type: string enum: - catalog - custom - local-installed description: Where this model comes from required: - provider - model - supportedFileTypes - source additionalProperties: false description: Hydrated model picker entry description: Curated featured models recents: type: array items: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider model: type: string description: Model ID baseURL: type: string format: uri description: Variant-specific base URL displayName: type: string description: Human-readable model name supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types supported by this model source: type: string enum: - catalog - custom - local-installed description: Where this model comes from required: - provider - model - supportedFileTypes - source additionalProperties: false description: Hydrated model picker entry description: Most recently used models favorites: type: array items: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider model: type: string description: Model ID baseURL: type: string format: uri description: Variant-specific base URL displayName: type: string description: Human-readable model name supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types supported by this model source: type: string enum: - catalog - custom - local-installed description: Where this model comes from required: - provider - model - supportedFileTypes - source additionalProperties: false description: Hydrated model picker entry description: User favorited models custom: type: array items: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider model: type: string description: Model ID baseURL: type: string format: uri description: Variant-specific base URL displayName: type: string description: Human-readable model name supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types supported by this model source: type: string enum: - catalog - custom - local-installed description: Where this model comes from required: - provider - model - supportedFileTypes - source additionalProperties: false description: Hydrated model picker entry description: User-defined custom models required: - featured - recents - favorites - custom additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints '404': description: Resource not found content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints '500': description: Internal server error content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints /api/llm/model-picker-state/recents: post: summary: Record Recent Model description: Records a model selection in recents. tags: - llm requestBody: required: true content: application/json: schema: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider model: type: string minLength: 1 description: Model ID baseURL: type: string format: uri description: Variant-specific base URL required: - provider - model additionalProperties: false description: Provider/model pair for model picker state operations responses: '200': description: Recent model recorded content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Success indicator required: - ok additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints '404': description: Resource not found content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints '500': description: Internal server error content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints /api/llm/model-picker-state/favorites/toggle: post: summary: Toggle Favorite Model description: Adds or removes a model from favorites. tags: - llm requestBody: required: true content: application/json: schema: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider model: type: string minLength: 1 description: Model ID baseURL: type: string format: uri description: Variant-specific base URL required: - provider - model additionalProperties: false description: Provider/model pair for model picker state operations responses: '200': description: Favorite toggled content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Success indicator isFavorite: type: boolean description: Whether the model is now favorited required: - ok - isFavorite additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints '404': description: Resource not found content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints '500': description: Internal server error content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints /api/llm/model-picker-state/favorites: put: summary: Set Favorite Models description: Replaces favorite models list. Used by migration or bulk updates. tags: - llm requestBody: required: true content: application/json: schema: type: object properties: favorites: type: array items: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider model: type: string minLength: 1 description: Model ID baseURL: type: string format: uri description: Variant-specific base URL required: - provider - model additionalProperties: false description: Provider/model pair for model picker state operations description: Complete list of favorite model references required: - favorites additionalProperties: false description: Request body for setting favorite models responses: '200': description: Favorites updated content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Success indicator count: type: integer minimum: 0 description: Number of favorites persisted required: - ok - count additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints '404': description: Resource not found content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints '500': description: Internal server error content: application/json: schema: type: object properties: code: type: string description: Error code message: type: string description: Error message scope: type: string description: Error scope type: type: string description: Error type context: type: object additionalProperties: true description: Error context recovery: anyOf: - type: string - type: array items: type: string description: Recovery guidance traceId: type: string description: Trace identifier endpoint: type: string description: Request endpoint method: type: string description: HTTP method required: - code - message - scope - type - traceId - endpoint - method additionalProperties: false description: Standard error response for model picker endpoints /api/llm/capabilities: get: summary: Get Model Capabilities description: >- Returns the capabilities (supported file types) for a specific provider/model combination. Handles gateway providers (dexto-nova, openrouter) by resolving to the underlying model capabilities. tags: - llm parameters: - schema: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider name required: true description: LLM provider name name: provider in: query - schema: type: string minLength: 1 description: Model name (supports both native and OpenRouter format) required: true description: Model name (supports both native and OpenRouter format) name: model in: query responses: '200': description: Model capabilities content: application/json: schema: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: Provider name model: type: string description: Model name as provided supportedFileTypes: type: array items: type: string enum: - pdf - image - audio - video - document description: File types supported by this model reasoning: type: object properties: capable: type: boolean description: >- Whether Dexto considers this provider/model reasoning-capable (derived from registry metadata plus explicit provider/model rules) paradigm: type: string enum: - effort - adaptive-effort - thinking-level - budget - none description: Reasoning control paradigm for this model variants: type: array items: type: object properties: id: type: string description: Native reasoning variant identifier label: type: string description: Display label for the native reasoning variant required: - id - label additionalProperties: false description: Native reasoning variants exposed to users supportedVariants: type: array items: type: string description: >- Native reasoning variant IDs supported for this model/provider defaultVariant: type: string description: >- Default reasoning variant used when no explicit override is set supportsBudgetTokens: type: boolean description: >- Whether this provider/model supports a budgetTokens-style escape hatch required: - capable - paradigm - variants - supportedVariants - supportsBudgetTokens additionalProperties: false description: >- Reasoning tuning capabilities derived from registry metadata and explicit provider/model rules required: - provider - model - supportedFileTypes - reasoning '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions: get: summary: List Sessions description: Retrieves a list of all active sessions tags: - sessions responses: '200': description: List of all active sessions content: application/json: schema: type: object properties: sessions: type: array items: type: object properties: id: type: string description: Unique session identifier createdAt: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms, null if unavailable) lastActivity: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: >- Last activity timestamp (Unix ms, null if unavailable) messageCount: type: integer minimum: 0 description: Total number of messages in session title: type: string nullable: true description: Optional session title tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Aggregate token usage across all models estimatedCost: type: number minimum: 0 description: Total estimated cost in USD across all models modelStats: type: array items: type: object properties: provider: type: string description: LLM provider identifier model: type: string description: Model identifier messageCount: type: integer minimum: 0 description: Number of messages using this model tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Token usage for this model estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this model firstUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: First use timestamp (Unix ms) lastUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last use timestamp (Unix ms) required: - provider - model - messageCount - tokenUsage - estimatedCost - firstUsedAt - lastUsedAt additionalProperties: false description: Per-model statistics within a session description: >- Per-model usage statistics (for multi-model sessions) usageTracking: type: object properties: hasUntrackedChatGPTLoginUsage: type: boolean description: >- Whether this session includes known untracked ChatGPT Login usage additionalProperties: false description: >- Known caveats or gaps in usage tracking for this session workspaceId: type: string nullable: true description: Associated workspace ID, if any parentSessionId: type: string nullable: true description: >- Parent session ID if this session was forked, otherwise null required: - id - createdAt - lastActivity - messageCount additionalProperties: false description: Session metadata description: Array of session metadata objects required: - sessions additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response post: summary: Create Session description: Creates a new session tags: - sessions requestBody: content: application/json: schema: type: object properties: sessionId: type: string description: A custom ID for the new session description: Request body for creating a new session responses: '201': description: Session created successfully content: application/json: schema: type: object properties: session: type: object properties: id: type: string description: Unique session identifier createdAt: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms, null if unavailable) lastActivity: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Last activity timestamp (Unix ms, null if unavailable) messageCount: type: integer minimum: 0 description: Total number of messages in session title: type: string nullable: true description: Optional session title tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Aggregate token usage across all models estimatedCost: type: number minimum: 0 description: Total estimated cost in USD across all models modelStats: type: array items: type: object properties: provider: type: string description: LLM provider identifier model: type: string description: Model identifier messageCount: type: integer minimum: 0 description: Number of messages using this model tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Token usage for this model estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this model firstUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: First use timestamp (Unix ms) lastUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last use timestamp (Unix ms) required: - provider - model - messageCount - tokenUsage - estimatedCost - firstUsedAt - lastUsedAt additionalProperties: false description: Per-model statistics within a session description: Per-model usage statistics (for multi-model sessions) usageTracking: type: object properties: hasUntrackedChatGPTLoginUsage: type: boolean description: >- Whether this session includes known untracked ChatGPT Login usage additionalProperties: false description: >- Known caveats or gaps in usage tracking for this session workspaceId: type: string nullable: true description: Associated workspace ID, if any parentSessionId: type: string nullable: true description: >- Parent session ID if this session was forked, otherwise null required: - id - createdAt - lastActivity - messageCount additionalProperties: false description: Newly created session metadata required: - session additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions/{sessionId}/fork: post: summary: Fork Session description: >- Creates a new child session by cloning the specified parent session history and metadata lineage. tags: - sessions parameters: - schema: type: string description: Parent session identifier required: true description: Parent session identifier name: sessionId in: path responses: '201': description: Forked session created successfully content: application/json: schema: type: object properties: session: type: object properties: id: type: string description: Unique session identifier createdAt: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms, null if unavailable) lastActivity: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Last activity timestamp (Unix ms, null if unavailable) messageCount: type: integer minimum: 0 description: Total number of messages in session title: type: string nullable: true description: Optional session title tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Aggregate token usage across all models estimatedCost: type: number minimum: 0 description: Total estimated cost in USD across all models modelStats: type: array items: type: object properties: provider: type: string description: LLM provider identifier model: type: string description: Model identifier messageCount: type: integer minimum: 0 description: Number of messages using this model tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Token usage for this model estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this model firstUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: First use timestamp (Unix ms) lastUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last use timestamp (Unix ms) required: - provider - model - messageCount - tokenUsage - estimatedCost - firstUsedAt - lastUsedAt additionalProperties: false description: Per-model statistics within a session description: Per-model usage statistics (for multi-model sessions) usageTracking: type: object properties: hasUntrackedChatGPTLoginUsage: type: boolean description: >- Whether this session includes known untracked ChatGPT Login usage additionalProperties: false description: >- Known caveats or gaps in usage tracking for this session workspaceId: type: string nullable: true description: Associated workspace ID, if any parentSessionId: type: string nullable: true description: >- Parent session ID if this session was forked, otherwise null required: - id - createdAt - lastActivity - messageCount additionalProperties: false description: Newly created child session metadata required: - session additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions/{sessionId}: get: summary: Get Session Details description: Fetches details for a specific session tags: - sessions parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path responses: '200': description: Session details with metadata content: application/json: schema: type: object properties: session: type: object properties: id: type: string description: Unique session identifier createdAt: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms, null if unavailable) lastActivity: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Last activity timestamp (Unix ms, null if unavailable) messageCount: type: integer minimum: 0 description: Total number of messages in session title: type: string nullable: true description: Optional session title tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Aggregate token usage across all models estimatedCost: type: number minimum: 0 description: Total estimated cost in USD across all models modelStats: type: array items: type: object properties: provider: type: string description: LLM provider identifier model: type: string description: Model identifier messageCount: type: integer minimum: 0 description: Number of messages using this model tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Token usage for this model estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this model firstUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: First use timestamp (Unix ms) lastUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last use timestamp (Unix ms) required: - provider - model - messageCount - tokenUsage - estimatedCost - firstUsedAt - lastUsedAt additionalProperties: false description: Per-model statistics within a session description: Per-model usage statistics (for multi-model sessions) usageTracking: type: object properties: hasUntrackedChatGPTLoginUsage: type: boolean description: >- Whether this session includes known untracked ChatGPT Login usage additionalProperties: false description: >- Known caveats or gaps in usage tracking for this session workspaceId: type: string nullable: true description: Associated workspace ID, if any parentSessionId: type: string nullable: true description: >- Parent session ID if this session was forked, otherwise null history: type: integer minimum: 0 description: Number of messages in history required: - id - createdAt - lastActivity - messageCount - history additionalProperties: false description: Session metadata with history count required: - session additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response delete: summary: Delete Session description: >- Permanently deletes a session and all its conversation history. This action cannot be undone tags: - sessions parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path responses: '200': description: Session deleted successfully content: application/json: schema: type: object properties: status: type: string enum: - deleted description: Deletion status sessionId: type: string description: ID of the deleted session required: - status - sessionId additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response patch: summary: Update Session Title description: Updates the title of an existing session tags: - sessions parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path requestBody: content: application/json: schema: type: object properties: title: type: string minLength: 1 maxLength: 120 description: New title for the session (maximum 120 characters) required: - title responses: '200': description: Session updated successfully content: application/json: schema: type: object properties: session: type: object properties: id: type: string description: Unique session identifier createdAt: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms, null if unavailable) lastActivity: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Last activity timestamp (Unix ms, null if unavailable) messageCount: type: integer minimum: 0 description: Total number of messages in session title: type: string nullable: true description: Optional session title tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Aggregate token usage across all models estimatedCost: type: number minimum: 0 description: Total estimated cost in USD across all models modelStats: type: array items: type: object properties: provider: type: string description: LLM provider identifier model: type: string description: Model identifier messageCount: type: integer minimum: 0 description: Number of messages using this model tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Token usage for this model estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this model firstUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: First use timestamp (Unix ms) lastUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last use timestamp (Unix ms) required: - provider - model - messageCount - tokenUsage - estimatedCost - firstUsedAt - lastUsedAt additionalProperties: false description: Per-model statistics within a session description: Per-model usage statistics (for multi-model sessions) usageTracking: type: object properties: hasUntrackedChatGPTLoginUsage: type: boolean description: >- Whether this session includes known untracked ChatGPT Login usage additionalProperties: false description: >- Known caveats or gaps in usage tracking for this session workspaceId: type: string nullable: true description: Associated workspace ID, if any parentSessionId: type: string nullable: true description: >- Parent session ID if this session was forked, otherwise null required: - id - createdAt - lastActivity - messageCount additionalProperties: false description: Updated session metadata required: - session additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions/{sessionId}/history: get: summary: Get Session History description: >- Retrieves the conversation history for a session along with processing status tags: - sessions parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path responses: '200': description: Session conversation history content: application/json: schema: type: object properties: history: type: array items: type: object properties: id: type: string format: uuid description: Unique message identifier (UUID) role: type: string enum: - system - user - assistant - tool description: Role of the message sender timestamp: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) content: anyOf: - type: string - nullable: true - type: array items: oneOf: - type: object properties: type: type: string enum: - text description: 'Part type: text' text: type: string description: Text content required: - type - text additionalProperties: false description: Text content part - type: object properties: type: type: string enum: - image description: 'Part type: image' image: type: string description: Base64-encoded image data mimeType: type: string description: MIME type of the image required: - type - image additionalProperties: false description: Image content part - type: object properties: type: type: string enum: - file description: 'Part type: file' data: type: string description: Base64-encoded file data mimeType: type: string description: MIME type of the file filename: type: string description: Optional filename required: - type - data - mimeType additionalProperties: false description: File content part - type: object properties: type: type: string enum: - resource description: 'Part type: resource' uri: type: string description: Canonical resource reference name: type: string description: Display name for the resource mimeType: type: string description: MIME type of the resource kind: type: string enum: - text - image - audio - video - binary description: >- Resource kind for rendering and prompt projection size: type: integer minimum: 0 description: Size in bytes metadata: type: object properties: mtimeMs: type: number minimum: 0 description: mtime in ms source: type: string enum: - filesystem - upload - generated - tool - remote description: How the resource was created additionalProperties: false description: Optional resource metadata required: - type - uri - name - mimeType - kind additionalProperties: false description: Canonical resource reference part - type: object properties: type: type: string enum: - ui-resource description: 'Part type: ui-resource' uri: type: string description: >- URI identifying the UI resource (must start with ui://) mimeType: type: string description: >- MIME type: text/html, text/uri-list, or application/vnd.mcp-ui.remote-dom content: type: string description: Inline HTML content or URL blob: type: string description: >- Base64-encoded content (alternative to content) metadata: type: object properties: title: type: string description: Display title for the UI resource preferredSize: type: object properties: width: type: number description: Preferred width in pixels height: type: number description: Preferred height in pixels required: - width - height additionalProperties: false description: Preferred rendering size additionalProperties: false description: Optional metadata for the UI resource required: - type - uri - mimeType additionalProperties: false description: >- UI Resource content part for MCP-UI interactive components description: >- Message content part (text, image, file, resource, or UI resource) description: Message content (string, null, or array of parts) reasoning: type: string description: Optional model reasoning text tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used additionalProperties: false description: Optional token usage accounting estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this response pricingStatus: type: string enum: - estimated - unpriced description: Whether pricing was resolved for this response usageScopeId: type: string description: >- Optional usage scope identifier for runtime-scoped metering model: type: string description: Model identifier for assistant messages provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: Provider identifier for assistant messages toolCalls: type: array items: type: object properties: id: type: string description: Unique identifier for this tool call type: type: string enum: - function description: >- Tool call type (currently only function is supported) function: type: object properties: name: type: string description: Name of the function to call arguments: type: string description: >- Arguments for the function in JSON string format required: - name - arguments additionalProperties: false description: Function call details required: - id - type - function additionalProperties: false description: Tool call made by the assistant description: Tool calls made by the assistant toolCallId: type: string description: ID of the tool call this message responds to name: type: string description: Name of the tool that produced this result success: type: boolean description: >- Whether tool execution succeeded (present for role=tool messages) required: - role - content additionalProperties: false description: Internal message representation description: Array of messages in conversation history isBusy: type: boolean description: Whether the session is currently processing a message required: - history - isBusy additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions/{sessionId}/system-prompt/contributors: get: summary: List Session System Prompt Contributors description: >- Lists static system prompt contributors that apply only to the specified session. tags: - sessions - config parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path responses: '200': description: Current session contributor list content: application/json: schema: type: object properties: contributors: type: array items: type: object properties: id: type: string description: Contributor identifier priority: type: number description: Contributor priority required: - id - priority additionalProperties: false description: Session-scoped system prompt contributor metadata. description: Registered session prompt contributors. required: - contributors additionalProperties: false '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response post: summary: Upsert Session System Prompt Contributor description: >- Adds or updates a static system prompt contributor that applies only to the specified session. Set enabled=false to remove it. tags: - sessions - config parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path requestBody: required: true content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Contributor identifier priority: type: integer minimum: 0 default: 45 description: Optional priority override enabled: type: boolean default: true description: >- Set false to remove the contributor instead of adding or updating it content: type: string description: >- Static contributor content for this session (required when enabled) required: - id additionalProperties: false description: Session-scoped system prompt contributor update payload. responses: '200': description: Session contributor upsert result content: application/json: schema: type: object properties: id: type: string description: Contributor identifier enabled: type: boolean description: Whether the contributor remains enabled priority: type: number description: Contributor priority replaced: type: boolean description: Whether an existing contributor was replaced removed: type: boolean description: Whether the contributor was removed contentLength: type: number description: Stored content length in characters truncated: type: boolean description: Whether the submitted content was truncated required: - id - enabled additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions/{sessionId}/cancel: post: summary: Cancel Session Run description: >- Cancels an in-flight agent run for the specified session. By default (soft cancel), only the current LLM call is cancelled and queued messages continue processing. Set clearQueue=true for hard cancel to also clear any queued messages. tags: - sessions parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path requestBody: required: false content: application/json: schema: type: object properties: clearQueue: type: boolean default: false description: >- If true (hard cancel), clears queued messages. If false (soft cancel, default), queued messages continue processing. additionalProperties: false responses: '200': description: Cancel operation result content: application/json: schema: type: object properties: cancelled: type: boolean description: Whether a run was cancelled sessionId: type: string description: Session ID queueCleared: type: boolean description: Whether queued messages were cleared clearedCount: type: number description: Number of queued messages cleared (0 if soft cancel) required: - cancelled - sessionId - queueCleared - clearedCount additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions/{sessionId}/events: get: summary: Attach Session Event Stream description: >- Attaches to the live SSE event stream for an already-running session without starting a new run. Use this to reattach after a page reload or connection interruption. tags: - sessions parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path responses: '200': description: SSE stream of live session events headers: Content-Type: description: SSE content type schema: type: string example: text/event-stream Cache-Control: description: Disable caching for stream schema: type: string example: no-cache Connection: description: Keep connection alive for streaming schema: type: string example: keep-alive X-Accel-Buffering: description: Disable nginx buffering schema: type: string example: 'no' content: text/event-stream: schema: type: string description: >- Server-Sent Events stream for an active session. Events use the same payloads as /message-stream. '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions/{sessionId}/load: get: summary: Load Session description: >- Validates and retrieves session information including processing status. The client should track the active session. tags: - sessions parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path responses: '200': description: Session information retrieved successfully content: application/json: schema: type: object properties: session: type: object properties: id: type: string description: Unique session identifier createdAt: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms, null if unavailable) lastActivity: type: integer nullable: true minimum: 0 exclusiveMinimum: true description: Last activity timestamp (Unix ms, null if unavailable) messageCount: type: integer minimum: 0 description: Total number of messages in session title: type: string nullable: true description: Optional session title tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Aggregate token usage across all models estimatedCost: type: number minimum: 0 description: Total estimated cost in USD across all models modelStats: type: array items: type: object properties: provider: type: string description: LLM provider identifier model: type: string description: Model identifier messageCount: type: integer minimum: 0 description: Number of messages using this model tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Token usage for this model estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this model firstUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: First use timestamp (Unix ms) lastUsedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last use timestamp (Unix ms) required: - provider - model - messageCount - tokenUsage - estimatedCost - firstUsedAt - lastUsedAt additionalProperties: false description: Per-model statistics within a session description: Per-model usage statistics (for multi-model sessions) usageTracking: type: object properties: hasUntrackedChatGPTLoginUsage: type: boolean description: >- Whether this session includes known untracked ChatGPT Login usage additionalProperties: false description: >- Known caveats or gaps in usage tracking for this session workspaceId: type: string nullable: true description: Associated workspace ID, if any parentSessionId: type: string nullable: true description: >- Parent session ID if this session was forked, otherwise null isBusy: type: boolean description: Whether the session is currently processing a message usageSummary: type: object properties: tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Aggregate token usage for the selected scope estimatedCost: type: number minimum: 0 description: Total estimated cost in USD for the selected scope hasUnpricedResponses: type: boolean description: >- Whether any response in the selected scope has usage but no resolved pricing modelStats: type: array items: type: object properties: provider: type: string description: LLM provider identifier model: type: string description: Model identifier messageCount: type: integer minimum: 0 description: >- Number of responses using this model in the selected scope tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: >- Token usage for this model in the selected scope estimatedCost: type: number minimum: 0 description: >- Estimated cost in USD for this model in the selected scope required: - provider - model - messageCount - tokenUsage - estimatedCost additionalProperties: false description: >- Per-model usage statistics within the selected scope required: - tokenUsage - estimatedCost - hasUnpricedResponses additionalProperties: false description: >- Exact usage summary derived from assistant message history activeUsageScopeId: type: string nullable: true description: Current runtime usage scope identifier, if configured activeUsageScope: type: object nullable: true properties: tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: Aggregate token usage for the selected scope estimatedCost: type: number minimum: 0 description: Total estimated cost in USD for the selected scope hasUnpricedResponses: type: boolean description: >- Whether any response in the selected scope has usage but no resolved pricing modelStats: type: array items: type: object properties: provider: type: string description: LLM provider identifier model: type: string description: Model identifier messageCount: type: integer minimum: 0 description: >- Number of responses using this model in the selected scope tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used required: - inputTokens - outputTokens - reasoningTokens - cacheReadTokens - cacheWriteTokens - totalTokens additionalProperties: false description: >- Token usage for this model in the selected scope estimatedCost: type: number minimum: 0 description: >- Estimated cost in USD for this model in the selected scope required: - provider - model - messageCount - tokenUsage - estimatedCost additionalProperties: false description: >- Per-model usage statistics within the selected scope scopeId: type: string description: Usage scope identifier required: - tokenUsage - estimatedCost - hasUnpricedResponses - scopeId additionalProperties: false description: >- Usage summary for the current runtime scope, if configured required: - id - createdAt - lastActivity - messageCount - isBusy - usageSummary - activeUsageScopeId - activeUsageScope additionalProperties: false description: Session metadata with processing status required: - session additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions/{sessionId}/clear-context: post: summary: Clear Session Context description: >- Clears the model context window for a session while preserving conversation history for review. tags: - sessions parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path responses: '200': description: Session context cleared successfully content: application/json: schema: type: object properties: status: type: string enum: - context cleared description: Context clear status sessionId: type: string description: Session ID required: - status - sessionId additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/sessions/{sessionId}/generate-title: post: summary: Generate Session Title description: >- Generates a descriptive title for the session using the first user message. Returns existing title if already set. tags: - sessions parameters: - schema: type: string description: Session identifier required: true description: Session identifier name: sessionId in: path responses: '200': description: Title generated successfully content: application/json: schema: type: object properties: title: type: string nullable: true description: Generated title, or null if generation failed sessionId: type: string description: Session ID required: - title - sessionId additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/search/messages: get: summary: Search Messages description: Searches for messages across all sessions or within a specific session tags: - search parameters: - schema: type: string minLength: 1 description: Search query string required: true description: Search query string name: q in: query - schema: type: number minimum: 1 maximum: 100 description: 'Maximum number of results to return (default: 20)' required: false description: 'Maximum number of results to return (default: 20)' name: limit in: query - schema: type: number nullable: true minimum: 0 description: 'Number of results to skip for pagination (default: 0)' required: false description: 'Number of results to skip for pagination (default: 0)' name: offset in: query - schema: type: string description: Limit search to a specific session required: false description: Limit search to a specific session name: sessionId in: query - schema: type: string enum: - user - assistant - system - tool description: Filter by message role required: false description: Filter by message role name: role in: query responses: '200': description: Message search results content: application/json: schema: type: object properties: results: type: array items: type: object properties: sessionId: type: string description: Session ID where the message was found message: type: object properties: id: type: string format: uuid description: Unique message identifier (UUID) role: type: string enum: - system - user - assistant - tool description: Role of the message sender timestamp: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) content: anyOf: - type: string - nullable: true - type: array items: oneOf: - type: object properties: type: type: string enum: - text description: 'Part type: text' text: type: string description: Text content required: - type - text additionalProperties: false description: Text content part - type: object properties: type: type: string enum: - image description: 'Part type: image' image: type: string description: Base64-encoded image data mimeType: type: string description: MIME type of the image required: - type - image additionalProperties: false description: Image content part - type: object properties: type: type: string enum: - file description: 'Part type: file' data: type: string description: Base64-encoded file data mimeType: type: string description: MIME type of the file filename: type: string description: Optional filename required: - type - data - mimeType additionalProperties: false description: File content part - type: object properties: type: type: string enum: - resource description: 'Part type: resource' uri: type: string description: Canonical resource reference name: type: string description: Display name for the resource mimeType: type: string description: MIME type of the resource kind: type: string enum: - text - image - audio - video - binary description: >- Resource kind for rendering and prompt projection size: type: integer minimum: 0 description: Size in bytes metadata: type: object properties: mtimeMs: type: number minimum: 0 description: mtime in ms source: type: string enum: - filesystem - upload - generated - tool - remote description: How the resource was created additionalProperties: false description: Optional resource metadata required: - type - uri - name - mimeType - kind additionalProperties: false description: Canonical resource reference part - type: object properties: type: type: string enum: - ui-resource description: 'Part type: ui-resource' uri: type: string description: >- URI identifying the UI resource (must start with ui://) mimeType: type: string description: >- MIME type: text/html, text/uri-list, or application/vnd.mcp-ui.remote-dom content: type: string description: Inline HTML content or URL blob: type: string description: >- Base64-encoded content (alternative to content) metadata: type: object properties: title: type: string description: Display title for the UI resource preferredSize: type: object properties: width: type: number description: Preferred width in pixels height: type: number description: Preferred height in pixels required: - width - height additionalProperties: false description: Preferred rendering size additionalProperties: false description: Optional metadata for the UI resource required: - type - uri - mimeType additionalProperties: false description: >- UI Resource content part for MCP-UI interactive components description: >- Message content part (text, image, file, resource, or UI resource) description: >- Message content (string, null, or array of parts) reasoning: type: string description: Optional model reasoning text tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used additionalProperties: false description: Optional token usage accounting estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this response pricingStatus: type: string enum: - estimated - unpriced description: Whether pricing was resolved for this response usageScopeId: type: string description: >- Optional usage scope identifier for runtime-scoped metering model: type: string description: Model identifier for assistant messages provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: Provider identifier for assistant messages toolCalls: type: array items: type: object properties: id: type: string description: Unique identifier for this tool call type: type: string enum: - function description: >- Tool call type (currently only function is supported) function: type: object properties: name: type: string description: Name of the function to call arguments: type: string description: >- Arguments for the function in JSON string format required: - name - arguments additionalProperties: false description: Function call details required: - id - type - function additionalProperties: false description: Tool call made by the assistant description: Tool calls made by the assistant toolCallId: type: string description: ID of the tool call this message responds to name: type: string description: Name of the tool that produced this result success: type: boolean description: >- Whether tool execution succeeded (present for role=tool messages) required: - role - content additionalProperties: false description: The message that matched the search matchedText: type: string description: The specific text that matched the search query context: type: string description: Context around the match for preview messageIndex: type: integer minimum: 0 description: Index of the message within the session required: - sessionId - message - matchedText - context - messageIndex additionalProperties: false description: Result of a message search description: Array of search results total: type: integer minimum: 0 description: Total number of results available hasMore: type: boolean description: Whether there are more results beyond the current page query: type: string description: Query that was searched required: - results - total - hasMore - query additionalProperties: false description: Message search response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/search/sessions: get: summary: Search Sessions description: Searches for sessions that contain the specified query tags: - search parameters: - schema: type: string minLength: 1 description: Search query string required: true description: Search query string name: q in: query responses: '200': description: Session search results content: application/json: schema: type: object properties: results: type: array items: type: object properties: sessionId: type: string description: Session ID matchCount: type: integer minimum: 0 description: Number of messages that matched in this session firstMatch: type: object properties: sessionId: type: string description: Session ID where the message was found message: type: object properties: id: type: string format: uuid description: Unique message identifier (UUID) role: type: string enum: - system - user - assistant - tool description: Role of the message sender timestamp: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) content: anyOf: - type: string - nullable: true - type: array items: oneOf: - type: object properties: type: type: string enum: - text description: 'Part type: text' text: type: string description: Text content required: - type - text additionalProperties: false description: Text content part - type: object properties: type: type: string enum: - image description: 'Part type: image' image: type: string description: Base64-encoded image data mimeType: type: string description: MIME type of the image required: - type - image additionalProperties: false description: Image content part - type: object properties: type: type: string enum: - file description: 'Part type: file' data: type: string description: Base64-encoded file data mimeType: type: string description: MIME type of the file filename: type: string description: Optional filename required: - type - data - mimeType additionalProperties: false description: File content part - type: object properties: type: type: string enum: - resource description: 'Part type: resource' uri: type: string description: Canonical resource reference name: type: string description: Display name for the resource mimeType: type: string description: MIME type of the resource kind: type: string enum: - text - image - audio - video - binary description: >- Resource kind for rendering and prompt projection size: type: integer minimum: 0 description: Size in bytes metadata: type: object properties: mtimeMs: type: number minimum: 0 description: mtime in ms source: type: string enum: - filesystem - upload - generated - tool - remote description: How the resource was created additionalProperties: false description: Optional resource metadata required: - type - uri - name - mimeType - kind additionalProperties: false description: Canonical resource reference part - type: object properties: type: type: string enum: - ui-resource description: 'Part type: ui-resource' uri: type: string description: >- URI identifying the UI resource (must start with ui://) mimeType: type: string description: >- MIME type: text/html, text/uri-list, or application/vnd.mcp-ui.remote-dom content: type: string description: Inline HTML content or URL blob: type: string description: >- Base64-encoded content (alternative to content) metadata: type: object properties: title: type: string description: Display title for the UI resource preferredSize: type: object properties: width: type: number description: Preferred width in pixels height: type: number description: Preferred height in pixels required: - width - height additionalProperties: false description: Preferred rendering size additionalProperties: false description: Optional metadata for the UI resource required: - type - uri - mimeType additionalProperties: false description: >- UI Resource content part for MCP-UI interactive components description: >- Message content part (text, image, file, resource, or UI resource) description: >- Message content (string, null, or array of parts) reasoning: type: string description: Optional model reasoning text tokenUsage: type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens reasoningTokens: type: integer minimum: 0 description: Number of reasoning tokens cacheReadTokens: type: integer minimum: 0 description: Number of cache read tokens cacheWriteTokens: type: integer minimum: 0 description: Number of cache write tokens totalTokens: type: integer minimum: 0 description: Total tokens used additionalProperties: false description: Optional token usage accounting estimatedCost: type: number minimum: 0 description: Estimated cost in USD for this response pricingStatus: type: string enum: - estimated - unpriced description: >- Whether pricing was resolved for this response usageScopeId: type: string description: >- Optional usage scope identifier for runtime-scoped metering model: type: string description: Model identifier for assistant messages provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: Provider identifier for assistant messages toolCalls: type: array items: type: object properties: id: type: string description: Unique identifier for this tool call type: type: string enum: - function description: >- Tool call type (currently only function is supported) function: type: object properties: name: type: string description: Name of the function to call arguments: type: string description: >- Arguments for the function in JSON string format required: - name - arguments additionalProperties: false description: Function call details required: - id - type - function additionalProperties: false description: Tool call made by the assistant description: Tool calls made by the assistant toolCallId: type: string description: ID of the tool call this message responds to name: type: string description: Name of the tool that produced this result success: type: boolean description: >- Whether tool execution succeeded (present for role=tool messages) required: - role - content additionalProperties: false description: The message that matched the search matchedText: type: string description: The specific text that matched the search query context: type: string description: Context around the match for preview messageIndex: type: integer minimum: 0 description: Index of the message within the session required: - sessionId - message - matchedText - context - messageIndex additionalProperties: false description: Preview of the first matching message metadata: type: object properties: createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Session creation timestamp lastActivity: type: integer minimum: 0 exclusiveMinimum: true description: Last activity timestamp messageCount: type: integer minimum: 0 description: Total messages in session required: - createdAt - lastActivity - messageCount additionalProperties: false description: Session metadata required: - sessionId - matchCount - firstMatch - metadata additionalProperties: false description: Result of a session search description: Array of session search results total: type: integer minimum: 0 description: Total number of sessions with matches hasMore: type: boolean description: >- Always false - session search returns all matching sessions without pagination query: type: string description: Query that was searched required: - results - total - hasMore - query additionalProperties: false description: Session search response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/mcp/servers: post: summary: Add MCP Server description: Connects a new MCP server dynamically tags: - mcp requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: A unique name for the server config: oneOf: - type: object properties: type: type: string enum: - stdio enabled: type: boolean default: true description: >- Whether this server is enabled (disabled servers are not connected) command: type: string args: type: array items: type: string default: [] description: >- Array of arguments for the command (e.g., ['script.js']) env: type: object additionalProperties: type: string default: {} description: >- Optional environment variables for the server process timeout: type: integer minimum: 0 exclusiveMinimum: true default: 30000 connectionMode: type: string enum: - strict - lenient default: lenient required: - type - command additionalProperties: false - type: object properties: type: type: string enum: - sse enabled: type: boolean default: true description: >- Whether this server is enabled (disabled servers are not connected) url: type: string description: URL for the SSE server endpoint headers: type: object additionalProperties: type: string default: {} timeout: type: integer minimum: 0 exclusiveMinimum: true default: 30000 connectionMode: type: string enum: - strict - lenient default: lenient required: - type - url additionalProperties: false - type: object properties: type: type: string enum: - http enabled: type: boolean default: true description: >- Whether this server is enabled (disabled servers are not connected) url: type: string description: URL for the HTTP server headers: type: object additionalProperties: type: string default: {} timeout: type: integer minimum: 0 exclusiveMinimum: true default: 30000 connectionMode: type: string enum: - strict - lenient default: lenient required: - type - url additionalProperties: false description: The server configuration object persistToAgent: type: boolean description: If true, saves the server to agent configuration file required: - name - config additionalProperties: false description: Request body for adding or updating an MCP server responses: '200': description: Server connected content: application/json: schema: type: object properties: status: type: string description: Connection status name: type: string description: Server name required: - status - name additionalProperties: false description: Server status response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response get: summary: List MCP Servers description: Gets a list of all connected and failed MCP servers tags: - mcp responses: '200': description: Servers list content: application/json: schema: type: object properties: servers: type: array items: type: object properties: id: type: string description: Server identifier name: type: string description: Server name status: type: string enum: - connected - disconnected - error - auth-required description: Server status required: - id - name - status additionalProperties: false description: MCP server information description: Array of server information required: - servers additionalProperties: false description: List of MCP servers '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/mcp/servers/{serverId}/config: get: summary: Get MCP Server Config description: Retrieves the configuration for a specific MCP server tags: - mcp parameters: - schema: type: string description: The ID of the MCP server required: true description: The ID of the MCP server name: serverId in: path responses: '200': description: Server configuration content: application/json: schema: type: object properties: name: type: string description: Server name config: oneOf: - type: object properties: type: type: string enum: - stdio enabled: type: boolean default: true description: >- Whether this server is enabled (disabled servers are not connected) command: type: string args: type: array items: type: string default: [] description: >- Array of arguments for the command (e.g., ['script.js']) env: type: object additionalProperties: type: string default: {} description: >- Optional environment variables for the server process timeout: type: integer minimum: 0 exclusiveMinimum: true default: 30000 connectionMode: type: string enum: - strict - lenient default: lenient required: - type - command additionalProperties: false - type: object properties: type: type: string enum: - sse enabled: type: boolean default: true description: >- Whether this server is enabled (disabled servers are not connected) url: type: string description: URL for the SSE server endpoint headers: type: object additionalProperties: type: string default: {} timeout: type: integer minimum: 0 exclusiveMinimum: true default: 30000 connectionMode: type: string enum: - strict - lenient default: lenient required: - type - url additionalProperties: false - type: object properties: type: type: string enum: - http enabled: type: boolean default: true description: >- Whether this server is enabled (disabled servers are not connected) url: type: string description: URL for the HTTP server headers: type: object additionalProperties: type: string default: {} timeout: type: integer minimum: 0 exclusiveMinimum: true default: 30000 connectionMode: type: string enum: - strict - lenient default: lenient required: - type - url additionalProperties: false description: Server configuration required: - name - config additionalProperties: false description: MCP server configuration response '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/mcp/servers/{serverId}: put: summary: Update MCP Server description: Updates configuration for an existing MCP server tags: - mcp parameters: - schema: type: string description: The ID of the MCP server required: true description: The ID of the MCP server name: serverId in: path requestBody: content: application/json: schema: type: object properties: config: oneOf: - type: object properties: type: type: string enum: - stdio enabled: type: boolean default: true description: >- Whether this server is enabled (disabled servers are not connected) command: type: string args: type: array items: type: string default: [] description: >- Array of arguments for the command (e.g., ['script.js']) env: type: object additionalProperties: type: string default: {} description: >- Optional environment variables for the server process timeout: type: integer minimum: 0 exclusiveMinimum: true default: 30000 connectionMode: type: string enum: - strict - lenient default: lenient required: - type - command additionalProperties: false - type: object properties: type: type: string enum: - sse enabled: type: boolean default: true description: >- Whether this server is enabled (disabled servers are not connected) url: type: string description: URL for the SSE server endpoint headers: type: object additionalProperties: type: string default: {} timeout: type: integer minimum: 0 exclusiveMinimum: true default: 30000 connectionMode: type: string enum: - strict - lenient default: lenient required: - type - url additionalProperties: false - type: object properties: type: type: string enum: - http enabled: type: boolean default: true description: >- Whether this server is enabled (disabled servers are not connected) url: type: string description: URL for the HTTP server headers: type: object additionalProperties: type: string default: {} timeout: type: integer minimum: 0 exclusiveMinimum: true default: 30000 connectionMode: type: string enum: - strict - lenient default: lenient required: - type - url additionalProperties: false description: The updated server configuration object persistToAgent: type: boolean description: If true, saves the server to agent configuration file required: - config additionalProperties: false description: Request body for updating an MCP server responses: '200': description: Server updated content: application/json: schema: type: object properties: status: type: string description: Connection status name: type: string description: Server name required: - status - name additionalProperties: false description: Server status response '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response delete: summary: Remove MCP Server description: Disconnects and removes an MCP server tags: - mcp parameters: - schema: type: string description: The ID of the MCP server required: true description: The ID of the MCP server name: serverId in: path responses: '200': description: Disconnected content: application/json: schema: type: object properties: status: type: string enum: - disconnected description: Disconnection status id: type: string description: Server identifier required: - status - id additionalProperties: false description: Server disconnection response '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/mcp/servers/{serverId}/tools: get: summary: List Server Tools description: Retrieves the list of tools available on a specific MCP server tags: - mcp parameters: - schema: type: string description: The ID of the MCP server required: true description: The ID of the MCP server name: serverId in: path responses: '200': description: Tools list content: application/json: schema: type: object properties: tools: type: array items: type: object properties: id: type: string description: Tool identifier name: type: string description: Tool name description: type: string description: Tool description inputSchema: type: object properties: type: type: string enum: - object description: Schema type, always "object" when present properties: type: object additionalProperties: type: object properties: type: type: string enum: - string - number - integer - boolean - object - array description: Property type description: type: string description: Property description enum: type: array items: anyOf: - type: string - type: number - type: boolean - nullable: true description: Allowed JSON Schema enum value description: Enum values default: type: object additionalProperties: true description: Default value format: type: string description: JSON Schema format hint additionalProperties: nullable: true description: JSON Schema property definition description: Property definitions required: type: array items: type: string description: Required property names additionalProperties: nullable: true description: JSON Schema for tool input parameters _meta: type: object additionalProperties: true description: >- Optional tool metadata (e.g., MCP Apps UI resource info) required: - id - name - description additionalProperties: false description: Tool information description: Array of available tools required: - tools additionalProperties: false description: List of tools from MCP server '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/mcp/servers/{serverId}/restart: post: summary: Restart MCP Server description: Restarts a connected MCP server tags: - mcp parameters: - schema: type: string description: The ID of the MCP server required: true description: The ID of the MCP server name: serverId in: path responses: '200': description: Server restarted content: application/json: schema: type: object properties: status: type: string enum: - restarted description: Restart status id: type: string description: Server identifier required: - status - id additionalProperties: false description: Server restart response '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/mcp/servers/{serverId}/tools/{toolName}/execute: post: summary: Execute MCP Tool description: Executes a tool on an MCP server directly tags: - mcp parameters: - schema: type: string description: The ID of the MCP server required: true description: The ID of the MCP server name: serverId in: path - schema: type: string description: The name of the tool to execute required: true description: The name of the tool to execute name: toolName in: path requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/JsonObject' - description: >- Tool execution parameters as JSON object. The specific fields depend on the tool being executed and are defined by the tool's inputSchema. responses: '200': description: Tool executed content: application/json: schema: type: object properties: success: type: boolean description: Whether tool execution succeeded data: type: object additionalProperties: true description: Tool execution result data error: type: string description: Error message if execution failed required: - success additionalProperties: false description: Tool execution response '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/mcp/servers/{serverId}/resources: get: summary: List Server Resources description: Retrieves all resources available from a specific MCP server tags: - mcp parameters: - schema: type: string description: The ID of the MCP server required: true description: The ID of the MCP server name: serverId in: path responses: '200': description: Server resources content: application/json: schema: type: object properties: success: type: boolean description: Success indicator resources: type: array items: type: object properties: uri: type: string description: Resolved resource URI for this server name: type: string description: Resource display name originalUri: type: string description: Original MCP resource URI serverName: type: string description: Owning MCP server name required: - uri - name - originalUri - serverName additionalProperties: false description: Resource exposed by a specific MCP server description: Array of available resources required: - success - resources additionalProperties: false description: List of resources from MCP server '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/mcp/servers/{serverId}/resources/{resourceId}/content: get: summary: Read Server Resource Content description: >- Reads content from a specific resource on an MCP server. This endpoint automatically constructs the qualified URI format (mcp:serverId:resourceId) tags: - mcp parameters: - schema: type: string description: The ID of the MCP server required: true description: The ID of the MCP server name: serverId in: path - schema: type: string minLength: 1 description: The URI-encoded resource identifier on that server required: true description: The URI-encoded resource identifier on that server name: resourceId in: path responses: '200': description: Resource content content: application/json: schema: type: object properties: success: type: boolean description: Success indicator data: type: object properties: content: $ref: '#/components/schemas/JsonValue' required: - content additionalProperties: false description: Resource content required: - success - data additionalProperties: false description: Resource content response '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/webhooks: post: summary: Register Webhook description: Registers a new webhook endpoint to receive agent events tags: - webhooks requestBody: content: application/json: schema: type: object properties: url: type: string format: uri description: >- The URL to send webhook events to (must be a valid HTTP/HTTPS URL) secret: type: string description: A secret key for HMAC signature verification description: type: string description: A description of the webhook for reference required: - url description: Request body for registering a webhook responses: '201': description: Webhook registered content: application/json: schema: type: object properties: webhook: type: object properties: id: type: string description: Unique webhook identifier url: type: string format: uri description: Webhook URL description: type: string description: Webhook description createdAt: type: string format: date-time description: Creation timestamp (ISO 8601) required: - id - url - createdAt additionalProperties: false description: Registered webhook details required: - webhook additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response get: summary: List Webhooks description: Retrieves a list of all registered webhooks tags: - webhooks responses: '200': description: List webhooks content: application/json: schema: type: object properties: webhooks: type: array items: type: object properties: id: type: string description: Unique webhook identifier url: type: string format: uri description: Webhook URL description: type: string description: Webhook description createdAt: type: string format: date-time description: Creation timestamp (ISO 8601) required: - id - url - createdAt additionalProperties: false description: Webhook response object description: Array of registered webhooks required: - webhooks additionalProperties: false '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/webhooks/{webhookId}: get: summary: Get Webhook Details description: Fetches details for a specific webhook tags: - webhooks parameters: - schema: type: string description: The webhook identifier required: true description: The webhook identifier name: webhookId in: path responses: '200': description: Webhook content: application/json: schema: type: object properties: webhook: type: object properties: id: type: string description: Unique webhook identifier url: type: string format: uri description: Webhook URL description: type: string description: Webhook description createdAt: type: string format: date-time description: Creation timestamp (ISO 8601) required: - id - url - createdAt additionalProperties: false description: Webhook details required: - webhook additionalProperties: false '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response delete: summary: Delete Webhook description: Permanently removes a webhook endpoint. This action cannot be undone tags: - webhooks parameters: - schema: type: string description: The webhook identifier required: true description: The webhook identifier name: webhookId in: path responses: '200': description: Removed content: application/json: schema: type: object properties: status: type: string enum: - removed description: Operation status indicating successful removal webhookId: type: string description: ID of the removed webhook required: - status - webhookId additionalProperties: false '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/webhooks/{webhookId}/test: post: summary: Test Webhook description: Sends a sample event to test webhook connectivity and configuration tags: - webhooks parameters: - schema: type: string description: The webhook identifier required: true description: The webhook identifier name: webhookId in: path responses: '200': description: Test result content: application/json: schema: type: object properties: test: type: string enum: - completed description: Test status indicating completion result: type: object properties: success: type: boolean description: Whether the webhook test succeeded statusCode: type: number description: HTTP status code from webhook responseTime: type: number description: Response time in milliseconds error: type: string description: Error message if test failed required: - success additionalProperties: false description: Test execution results required: - test - result additionalProperties: false '404': description: Not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/prompts: get: summary: List Prompts description: >- Retrieves all available prompts, including both built-in and custom prompts tags: - prompts responses: '200': description: List all prompts content: application/json: schema: type: object properties: prompts: type: array items: type: object properties: name: type: string description: Prompt name title: type: string description: Prompt title description: type: string description: Prompt description arguments: type: array items: type: object properties: name: type: string description: Argument name description: type: string description: Argument description required: type: boolean description: Whether the argument is required required: - name additionalProperties: false description: Prompt argument definition description: Array of argument definitions disableModelInvocation: type: boolean description: Exclude from auto-invocation list in system prompt userInvocable: type: boolean description: Whether to show in slash command menu allowedTools: type: array items: type: string description: Tools to auto-approve when this prompt is active toolkits: type: array items: type: string description: Toolkits to load when invoked model: type: string description: Model to use when this prompt is invoked context: type: string enum: - inline - fork description: Execution context for this prompt agent: type: string description: Agent ID to use for fork execution source: type: string enum: - mcp - config - custom description: Source of the prompt displayName: type: string description: Base display name set by provider commandName: type: string description: Collision-resolved slash command name metadata: type: object additionalProperties: true description: Additional metadata required: - name - source additionalProperties: false description: Enhanced prompt information description: Array of available prompts required: - prompts additionalProperties: false description: Prompts list response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/prompts/custom: post: summary: Create Custom Prompt description: >- Creates a new custom prompt with optional resource attachment. Maximum request size: 10MB tags: - prompts requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Unique name for the custom prompt title: type: string description: Display title for the prompt description: type: string description: Description of what the prompt does content: type: string minLength: 1 description: >- The prompt content text (can include {{argumentName}} placeholders) arguments: type: array items: type: object properties: name: type: string minLength: 1 description: Argument name description: type: string description: Argument description required: type: boolean description: Whether the argument is required required: - name additionalProperties: false description: Array of argument definitions resource: type: object properties: data: type: string minLength: 1 description: Base64-encoded resource data mimeType: type: string minLength: 1 description: >- MIME type of the resource (e.g., text/plain, application/pdf) filename: type: string description: Resource filename required: - data - mimeType additionalProperties: false description: Attach a resource to this prompt required: - name - content additionalProperties: false description: >- Request body for creating a custom prompt with optional resource attachment responses: '201': description: Custom prompt created content: application/json: schema: type: object properties: prompt: type: object properties: name: type: string description: Prompt name title: type: string description: Prompt title description: type: string description: Prompt description arguments: type: array items: type: object properties: name: type: string description: Argument name description: type: string description: Argument description required: type: boolean description: Whether the argument is required required: - name additionalProperties: false description: Prompt argument definition description: Array of argument definitions disableModelInvocation: type: boolean description: Exclude from auto-invocation list in system prompt userInvocable: type: boolean description: Whether to show in slash command menu allowedTools: type: array items: type: string description: Tools to auto-approve when this prompt is active toolkits: type: array items: type: string description: Toolkits to load when invoked model: type: string description: Model to use when this prompt is invoked context: type: string enum: - inline - fork description: Execution context for this prompt agent: type: string description: Agent ID to use for fork execution source: type: string enum: - mcp - config - custom description: Source of the prompt displayName: type: string description: Base display name set by provider commandName: type: string description: Collision-resolved slash command name metadata: type: object additionalProperties: true description: Additional metadata required: - name - source additionalProperties: false description: Created prompt information required: - prompt additionalProperties: false description: Create prompt response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/prompts/custom/{name}: delete: summary: Delete Custom Prompt description: Permanently deletes a custom prompt. Built-in prompts cannot be deleted tags: - prompts parameters: - schema: type: string minLength: 1 description: The prompt name required: true description: The prompt name name: name in: path responses: '204': description: Prompt deleted /api/prompts/{name}: get: summary: Get Prompt Definition description: Fetches the definition for a specific prompt tags: - prompts parameters: - schema: type: string minLength: 1 description: The prompt name required: true description: The prompt name name: name in: path responses: '200': description: Prompt definition content: application/json: schema: type: object properties: definition: type: object properties: name: type: string description: Prompt name title: type: string description: Prompt title description: type: string description: Prompt description arguments: type: array items: type: object properties: name: type: string description: Argument name description: type: string description: Argument description required: type: boolean description: Whether the argument is required required: - name additionalProperties: false description: Prompt argument definition description: Array of argument definitions disableModelInvocation: type: boolean description: Exclude from auto-invocation list in system prompt userInvocable: type: boolean description: Whether to show in slash command menu allowedTools: type: array items: type: string description: Tools to auto-approve when this prompt is active toolkits: type: array items: type: string description: Toolkits to load when invoked model: type: string description: Model to use when this prompt is invoked context: type: string enum: - inline - fork description: Execution context for this prompt agent: type: string description: Agent ID to use for fork execution required: - name additionalProperties: false description: Prompt definition required: - definition additionalProperties: false description: Get prompt definition response '404': description: Prompt not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/prompts/{name}/resolve: get: summary: Resolve Prompt description: >- Resolves a prompt template with provided arguments and returns the final text with resources tags: - prompts parameters: - schema: type: string minLength: 1 description: The prompt name required: true description: The prompt name name: name in: path - schema: type: string description: Additional context for prompt resolution required: false description: Additional context for prompt resolution name: context in: query - schema: type: string description: >- Arguments to substitute in the prompt template (pass as a JSON string) required: false description: >- Arguments to substitute in the prompt template (pass as a JSON string) name: args in: query responses: '200': description: Resolved prompt content content: application/json: schema: type: object properties: text: type: string description: Resolved prompt text resources: type: array items: type: string description: Array of resource identifiers required: - text - resources additionalProperties: false description: Resolve prompt response '404': description: Prompt not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/resources: get: summary: List All Resources description: >- Retrieves a list of all available resources from all sources (MCP servers and internal providers) tags: - resources responses: '200': description: List all resources content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Indicates successful response resources: type: array items: type: object properties: uri: type: string description: Resource URI name: type: string description: Resource name description: type: string description: Resource description mimeType: type: string description: MIME type of the resource source: type: string enum: - mcp - internal description: Source system that provides this resource serverName: type: string description: Original server/provider name (for MCP resources) size: type: number description: Size of the resource in bytes (if known) lastModified: type: string format: date-time description: Last modified timestamp (ISO 8601 string) metadata: type: object additionalProperties: allOf: - $ref: '#/components/schemas/JsonValue' - $ref: '#/components/schemas/JsonValue' description: Additional metadata specific to the resource type required: - uri - source additionalProperties: false description: Resource metadata description: Array of all available resources from all sources required: - ok - resources additionalProperties: false description: List of all resources '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/resources/{resourceId}/content: get: summary: Read Resource Content description: >- Reads the content of a specific resource by its URI. The resource ID in the URL must be URI-encoded tags: - resources parameters: - schema: type: string minLength: 1 description: The URI-encoded resource identifier required: true description: The URI-encoded resource identifier name: resourceId in: path responses: '200': description: Resource content content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Indicates successful response content: type: object properties: contents: type: array items: type: object properties: uri: type: string description: Resource URI mimeType: type: string description: MIME type of the content text: type: string description: Text content (for text resources) blob: type: string description: >- Base64-encoded binary content (for binary resources) required: - uri additionalProperties: false description: Resource content item description: Array of content items (typically one item) _meta: type: object additionalProperties: true description: Optional metadata about the resource required: - contents additionalProperties: false description: Resource content from MCP ReadResourceResult required: - ok - content additionalProperties: false description: Resource content response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/resources/{resourceId}: head: summary: Check Resource Exists description: Checks if a resource exists by its URI without retrieving its content tags: - resources parameters: - schema: type: string minLength: 1 description: The URI-encoded resource identifier required: true description: The URI-encoded resource identifier name: resourceId in: path responses: '200': description: Resource exists '404': description: Resource not found /api/memory: post: summary: Create Memory description: Creates a new memory tags: - memory requestBody: content: application/json: schema: type: object properties: content: type: string minLength: 1 maxLength: 10000 description: The memory content tags: type: array items: type: string minLength: 1 maxLength: 50 maxItems: 10 description: Optional tags metadata: type: object properties: source: type: string enum: - user - system description: Source of the memory pinned: type: boolean description: Whether this memory is pinned for auto-loading additionalProperties: nullable: true description: Optional metadata required: - content additionalProperties: false description: Input for creating a new memory responses: '201': description: Memory created content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Indicates successful response memory: type: object properties: id: type: string minLength: 1 description: Unique identifier for the memory content: type: string minLength: 1 maxLength: 10000 description: The actual memory content createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) updatedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last update timestamp (Unix ms) tags: type: array items: type: string minLength: 1 maxLength: 50 maxItems: 10 description: Optional tags for categorization metadata: type: object properties: source: type: string enum: - user - system description: Source of the memory pinned: type: boolean description: Whether this memory is pinned for auto-loading additionalProperties: nullable: true description: Additional metadata required: - id - content - createdAt - updatedAt additionalProperties: false description: The created or retrieved memory required: - ok - memory additionalProperties: false description: Single memory response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response get: summary: List Memories description: Retrieves a list of all memories with optional filtering tags: - memory parameters: - schema: type: string description: Comma-separated list of tags to filter by required: false description: Comma-separated list of tags to filter by name: tags in: query - schema: type: string enum: - user - system description: Filter by source (user or system) required: false description: Filter by source (user or system) name: source in: query - schema: type: string description: Filter by pinned status (true or false) required: false description: Filter by pinned status (true or false) name: pinned in: query - schema: type: string description: Maximum number of memories to return required: false description: Maximum number of memories to return name: limit in: query - schema: type: string description: Number of memories to skip required: false description: Number of memories to skip name: offset in: query responses: '200': description: List memories content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Indicates successful response memories: type: array items: type: object properties: id: type: string minLength: 1 description: Unique identifier for the memory content: type: string minLength: 1 maxLength: 10000 description: The actual memory content createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) updatedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last update timestamp (Unix ms) tags: type: array items: type: string minLength: 1 maxLength: 50 maxItems: 10 description: Optional tags for categorization metadata: type: object properties: source: type: string enum: - user - system description: Source of the memory pinned: type: boolean description: Whether this memory is pinned for auto-loading additionalProperties: nullable: true description: Additional metadata required: - id - content - createdAt - updatedAt additionalProperties: false description: Memory item stored in the system description: List of memories required: - ok - memories additionalProperties: false description: Multiple memories response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/memory/{id}: get: summary: Get Memory by ID description: Retrieves a specific memory by its unique identifier tags: - memory parameters: - schema: type: string minLength: 1 description: Memory unique identifier required: true description: Memory unique identifier name: id in: path responses: '200': description: Memory details content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Indicates successful response memory: type: object properties: id: type: string minLength: 1 description: Unique identifier for the memory content: type: string minLength: 1 maxLength: 10000 description: The actual memory content createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) updatedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last update timestamp (Unix ms) tags: type: array items: type: string minLength: 1 maxLength: 50 maxItems: 10 description: Optional tags for categorization metadata: type: object properties: source: type: string enum: - user - system description: Source of the memory pinned: type: boolean description: Whether this memory is pinned for auto-loading additionalProperties: nullable: true description: Additional metadata required: - id - content - createdAt - updatedAt additionalProperties: false description: The created or retrieved memory required: - ok - memory additionalProperties: false description: Single memory response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response put: summary: Update Memory description: Updates an existing memory. Only provided fields will be updated tags: - memory parameters: - schema: type: string minLength: 1 description: Memory unique identifier required: true description: Memory unique identifier name: id in: path requestBody: content: application/json: schema: type: object properties: content: type: string minLength: 1 maxLength: 10000 description: Updated content tags: type: array items: type: string minLength: 1 maxLength: 50 maxItems: 10 description: Updated tags (replaces existing) metadata: type: object properties: source: type: string enum: - user - system description: Source of the memory pinned: type: boolean description: Whether this memory is pinned for auto-loading additionalProperties: nullable: true description: Updated metadata (merges with existing) additionalProperties: false description: Input for updating an existing memory responses: '200': description: Memory updated content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Indicates successful response memory: type: object properties: id: type: string minLength: 1 description: Unique identifier for the memory content: type: string minLength: 1 maxLength: 10000 description: The actual memory content createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) updatedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last update timestamp (Unix ms) tags: type: array items: type: string minLength: 1 maxLength: 50 maxItems: 10 description: Optional tags for categorization metadata: type: object properties: source: type: string enum: - user - system description: Source of the memory pinned: type: boolean description: Whether this memory is pinned for auto-loading additionalProperties: nullable: true description: Additional metadata required: - id - content - createdAt - updatedAt additionalProperties: false description: The created or retrieved memory required: - ok - memory additionalProperties: false description: Single memory response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response delete: summary: Delete Memory description: Permanently deletes a memory. This action cannot be undone tags: - memory parameters: - schema: type: string minLength: 1 description: Memory unique identifier required: true description: Memory unique identifier name: id in: path responses: '200': description: Memory deleted content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Indicates successful response message: type: string description: Deletion confirmation message required: - ok - message additionalProperties: false description: Memory deletion response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/workspaces: get: summary: List Workspaces description: Retrieves all known workspaces tags: - workspaces responses: '200': description: List of workspaces content: application/json: schema: type: object properties: workspaces: type: array items: type: object properties: id: type: string description: Workspace identifier path: type: string description: Workspace root path name: type: string nullable: true description: Optional workspace display name createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) lastActiveAt: type: integer minimum: 0 exclusiveMinimum: true description: Last active timestamp (Unix ms) required: - id - path - createdAt - lastActiveAt additionalProperties: false description: Workspace metadata description: Workspace list required: - workspaces additionalProperties: false '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/workspaces/active: get: summary: Get Active Workspace description: Returns the active workspace, if any tags: - workspaces responses: '200': description: Active workspace content: application/json: schema: type: object properties: workspace: type: object nullable: true properties: id: type: string description: Workspace identifier path: type: string description: Workspace root path name: type: string nullable: true description: Optional workspace display name createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) lastActiveAt: type: integer minimum: 0 exclusiveMinimum: true description: Last active timestamp (Unix ms) required: - id - path - createdAt - lastActiveAt additionalProperties: false description: Active workspace or null if none is set required: - workspace additionalProperties: false '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response post: summary: Set Active Workspace description: Sets the active workspace for this runtime tags: - workspaces requestBody: content: application/json: schema: type: object properties: path: type: string minLength: 1 description: Absolute workspace root path name: type: string description: Optional workspace display name required: - path additionalProperties: false description: Request body for setting the active workspace responses: '200': description: Active workspace updated content: application/json: schema: type: object properties: workspace: type: object properties: id: type: string description: Workspace identifier path: type: string description: Workspace root path name: type: string nullable: true description: Optional workspace display name createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) lastActiveAt: type: integer minimum: 0 exclusiveMinimum: true description: Last active timestamp (Unix ms) required: - id - path - createdAt - lastActiveAt additionalProperties: false description: Updated active workspace required: - workspace additionalProperties: false '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response delete: summary: Clear Active Workspace description: Clears the active workspace for this runtime tags: - workspaces responses: '200': description: Active workspace cleared content: application/json: schema: type: object properties: workspace: type: object nullable: true properties: id: type: string description: Workspace identifier path: type: string description: Workspace root path name: type: string nullable: true description: Optional workspace display name createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) lastActiveAt: type: integer minimum: 0 exclusiveMinimum: true description: Last active timestamp (Unix ms) required: - id - path - createdAt - lastActiveAt additionalProperties: false description: Active workspace or null if none is set required: - workspace additionalProperties: false '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/schedules: get: summary: List Schedules description: Retrieves all automation schedules tags: - schedules responses: '200': description: List of schedules content: application/json: schema: type: object properties: schedules: type: array items: type: object properties: id: type: string description: Schedule ID name: type: string description: Schedule name cronExpression: type: string description: Cron expression timezone: type: string description: Timezone for schedule enabled: type: boolean description: Whether the schedule is enabled task: type: object properties: instruction: type: string description: Instruction to execute metadata: type: object additionalProperties: true description: Optional task metadata required: - instruction additionalProperties: false description: Schedule task configuration sessionMode: type: string enum: - ephemeral - dedicated - inherit - fixed description: Session context mode sessionId: type: string description: Session ID when using fixed/inherit mode workspacePath: type: string description: Workspace path override createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) updatedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last update timestamp (Unix ms) lastRunAt: type: integer minimum: 0 exclusiveMinimum: true description: Last run timestamp (Unix ms) nextRunAt: type: integer minimum: 0 exclusiveMinimum: true description: Next run timestamp (Unix ms) runCount: type: integer minimum: 0 description: Total executions successCount: type: integer minimum: 0 description: Successful executions failureCount: type: integer minimum: 0 description: Failed executions lastError: type: string description: Last execution error, if any required: - id - name - cronExpression - timezone - enabled - task - sessionMode - createdAt - updatedAt - runCount - successCount - failureCount additionalProperties: false description: Automation schedule description: Schedule list required: - schedules additionalProperties: false description: List schedules response '500': description: Failed to list schedules content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '503': description: Scheduler tools are not enabled content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response post: summary: Create Schedule description: Creates a new automation schedule tags: - schedules requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Schedule name instruction: type: string minLength: 1 description: Instruction to run on schedule cronExpression: type: string minLength: 1 description: Cron expression timezone: type: string description: Timezone for schedule enabled: type: boolean description: Whether the schedule is enabled workspacePath: type: string nullable: true description: Optional workspace path for scheduled runs required: - name - instruction - cronExpression additionalProperties: false description: Request body for creating a schedule responses: '201': description: Created schedule content: application/json: schema: type: object properties: schedule: type: object properties: id: type: string description: Schedule ID name: type: string description: Schedule name cronExpression: type: string description: Cron expression timezone: type: string description: Timezone for schedule enabled: type: boolean description: Whether the schedule is enabled task: type: object properties: instruction: type: string description: Instruction to execute metadata: type: object additionalProperties: true description: Optional task metadata required: - instruction additionalProperties: false description: Schedule task configuration sessionMode: type: string enum: - ephemeral - dedicated - inherit - fixed description: Session context mode sessionId: type: string description: Session ID when using fixed/inherit mode workspacePath: type: string description: Workspace path override createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) updatedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last update timestamp (Unix ms) lastRunAt: type: integer minimum: 0 exclusiveMinimum: true description: Last run timestamp (Unix ms) nextRunAt: type: integer minimum: 0 exclusiveMinimum: true description: Next run timestamp (Unix ms) runCount: type: integer minimum: 0 description: Total executions successCount: type: integer minimum: 0 description: Successful executions failureCount: type: integer minimum: 0 description: Failed executions lastError: type: string description: Last execution error, if any required: - id - name - cronExpression - timezone - enabled - task - sessionMode - createdAt - updatedAt - runCount - successCount - failureCount additionalProperties: false description: Automation schedule required: - schedule additionalProperties: false description: Create schedule response '400': description: Validation error content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '429': description: Schedule limit reached content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '500': description: Failed to create schedule content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '503': description: Scheduler tools are not enabled content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response /api/schedules/{scheduleId}: patch: summary: Update Schedule description: Updates an existing schedule tags: - schedules parameters: - schema: type: string minLength: 1 description: Schedule ID required: true description: Schedule ID name: scheduleId in: path requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Schedule name instruction: type: string minLength: 1 description: Instruction to run on schedule cronExpression: type: string minLength: 1 description: Cron expression timezone: type: string description: Timezone for schedule enabled: type: boolean description: Whether the schedule is enabled workspacePath: type: string nullable: true description: Optional workspace path for scheduled runs additionalProperties: false description: Request body for updating a schedule responses: '200': description: Updated schedule content: application/json: schema: type: object properties: schedule: type: object properties: id: type: string description: Schedule ID name: type: string description: Schedule name cronExpression: type: string description: Cron expression timezone: type: string description: Timezone for schedule enabled: type: boolean description: Whether the schedule is enabled task: type: object properties: instruction: type: string description: Instruction to execute metadata: type: object additionalProperties: true description: Optional task metadata required: - instruction additionalProperties: false description: Schedule task configuration sessionMode: type: string enum: - ephemeral - dedicated - inherit - fixed description: Session context mode sessionId: type: string description: Session ID when using fixed/inherit mode workspacePath: type: string description: Workspace path override createdAt: type: integer minimum: 0 exclusiveMinimum: true description: Creation timestamp (Unix ms) updatedAt: type: integer minimum: 0 exclusiveMinimum: true description: Last update timestamp (Unix ms) lastRunAt: type: integer minimum: 0 exclusiveMinimum: true description: Last run timestamp (Unix ms) nextRunAt: type: integer minimum: 0 exclusiveMinimum: true description: Next run timestamp (Unix ms) runCount: type: integer minimum: 0 description: Total executions successCount: type: integer minimum: 0 description: Successful executions failureCount: type: integer minimum: 0 description: Failed executions lastError: type: string description: Last execution error, if any required: - id - name - cronExpression - timezone - enabled - task - sessionMode - createdAt - updatedAt - runCount - successCount - failureCount additionalProperties: false description: Automation schedule required: - schedule additionalProperties: false description: Update schedule response '400': description: Validation error content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '404': description: Schedule not found content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '500': description: Failed to update schedule content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '503': description: Scheduler tools are not enabled content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response delete: summary: Delete Schedule description: Deletes an automation schedule tags: - schedules parameters: - schema: type: string minLength: 1 description: Schedule ID required: true description: Schedule ID name: scheduleId in: path responses: '200': description: Schedule deleted content: application/json: schema: type: object properties: deleted: type: boolean description: Whether the schedule was deleted required: - deleted additionalProperties: false description: Delete schedule response '404': description: Schedule not found content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '500': description: Failed to delete schedule content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '503': description: Scheduler tools are not enabled content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response /api/schedules/{scheduleId}/trigger: post: summary: Trigger Schedule description: >- Runs a schedule immediately and waits for execution to complete (bounded by executionTimeout, default 5 minutes). Clients should set timeouts accordingly. tags: - schedules parameters: - schema: type: string minLength: 1 description: Schedule ID required: true description: Schedule ID name: scheduleId in: path responses: '200': description: Schedule triggered content: application/json: schema: type: object properties: scheduled: type: boolean description: >- Whether the schedule was queued. Execution is omitted when false. execution: type: object properties: id: type: string description: Execution log ID scheduleId: type: string description: Schedule ID triggeredAt: type: integer minimum: 0 exclusiveMinimum: true description: Trigger timestamp (Unix ms) completedAt: type: integer minimum: 0 exclusiveMinimum: true description: Completion timestamp (Unix ms) status: type: string enum: - pending - success - failed - timeout description: Execution status duration: type: integer minimum: 0 description: Execution duration in ms error: type: string description: Execution error, if any result: type: string description: Execution result, if any required: - id - scheduleId - triggeredAt - status additionalProperties: false description: Execution log (present when scheduled is true) required: - scheduled additionalProperties: false description: Trigger schedule response '404': description: Schedule not found content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '500': description: Failed to trigger schedule content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response '503': description: Scheduler tools are not enabled content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Indicates failed response error: type: object properties: message: type: string description: Error message code: type: string description: Error code details: type: object additionalProperties: true description: Additional error details required: - message additionalProperties: false description: Error details required: - ok - error additionalProperties: false description: Error API response /api/approvals: get: summary: Get Pending Approvals description: >- Fetch all pending approval requests for a session. Use this to restore UI state after page refresh. tags: - approvals parameters: - schema: type: string description: The session ID to fetch pending approvals for required: true description: The session ID to fetch pending approvals for name: sessionId in: query responses: '200': description: List of pending approval requests content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Success indicator approvals: type: array items: type: object properties: approvalId: type: string description: The unique ID of the approval request type: type: string description: >- The type of approval (tool_confirmation, elicitation, etc.) sessionId: type: string description: The session ID if applicable timeout: type: number description: Timeout in milliseconds timestamp: type: string description: ISO timestamp when the request was created metadata: allOf: - $ref: '#/components/schemas/JsonObject' - description: Type-specific metadata for the pending approval required: - approvalId - type - timestamp - metadata description: A pending approval request description: List of pending approval requests required: - ok - approvals description: Response containing pending approval requests '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/approvals/{approvalId}: post: summary: Submit Approval Decision description: Submit a user decision for a pending approval request tags: - approvals parameters: - schema: type: string description: The ID of the approval request required: true description: The ID of the approval request name: approvalId in: path - schema: type: string description: Optional key to ensure idempotent processing required: false description: Optional key to ensure idempotent processing name: Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: status: type: string enum: - approved - denied - cancelled description: The user decision formData: type: object additionalProperties: true description: Optional form data provided by the user (for elicitation) rememberChoice: type: boolean description: Whether to remember this choice for future requests rememberPattern: type: string description: Optional approval pattern to remember for future requests rememberDirectory: type: boolean description: >- Whether to remember the approved directory for future requests reason: type: string enum: - user_denied - system_denied - timeout - user_cancelled - system_cancelled - validation_failed - elicitation_disabled description: Optional structured denial or cancellation reason message: type: string description: Optional freeform denial or cancellation message required: - status additionalProperties: false description: Request body for submitting an approval decision responses: '200': description: Approval processed successfully content: application/json: schema: type: object properties: ok: type: boolean description: Whether the approval was successfully processed approvalId: type: string description: The ID of the processed approval status: type: string enum: - approved - denied - cancelled description: The final status required: - ok - approvalId - status description: Response after processing approval '400': description: Validation error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Approval request not found or expired content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Approval processing failed content: application/json: schema: type: object properties: ok: type: boolean description: Whether the approval was successfully processed approvalId: type: string description: The ID of the processed approval status: type: string enum: - approved - denied - cancelled description: The final status required: - ok - approvalId - status description: Response after processing approval '503': description: >- Approval coordinator unavailable (server not initialized for approvals) content: application/json: schema: type: object properties: ok: type: boolean description: Whether the approval was successfully processed approvalId: type: string description: The ID of the processed approval status: type: string enum: - approved - denied - cancelled description: The final status required: - ok - approvalId - status description: Response after processing approval /api/agents: get: summary: List Agents description: Retrieves all agents (installed, available, and current active agent) tags: - agents responses: '200': description: List all agents content: application/json: schema: type: object properties: installed: type: array items: type: object properties: id: type: string description: Unique agent identifier name: type: string description: Agent name description: type: string description: Agent description author: type: string description: Agent author tags: type: array items: type: string description: Agent tags type: type: string enum: - builtin - custom description: Agent type required: - id - name - description - type additionalProperties: false description: Agent registry entry description: Agents installed locally available: type: array items: type: object properties: id: type: string description: Unique agent identifier name: type: string description: Agent name description: type: string description: Agent description author: type: string description: Agent author tags: type: array items: type: string description: Agent tags type: type: string enum: - builtin - custom description: Agent type required: - id - name - description - type additionalProperties: false description: Agent registry entry description: Agents available from registry current: type: object properties: id: type: string nullable: true description: Agent identifier (null if no active agent) name: type: string nullable: true description: Agent display name (null if no active agent) required: - id - name additionalProperties: false description: Currently active agent required: - installed - available - current additionalProperties: false description: List of all agents '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agents/current: get: summary: Get Current Agent description: Retrieves the currently active agent tags: - agents responses: '200': description: Current agent content: application/json: schema: type: object properties: id: type: string nullable: true description: Agent identifier (null if no active agent) name: type: string nullable: true description: Agent display name (null if no active agent) required: - id - name additionalProperties: false description: Basic agent information (nullable) '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agents/install: post: summary: Install Agent description: Installs an agent from the registry or from a custom source tags: - agents requestBody: content: application/json: schema: anyOf: - type: object properties: id: type: string minLength: 1 description: Unique agent identifier name: type: string description: Display name (defaults to derived from id) sourcePath: type: string minLength: 1 description: Path to agent configuration file or directory metadata: type: object properties: description: type: string minLength: 1 description: Human-readable description of the agent author: type: string minLength: 1 description: Agent author or organization name tags: type: array items: type: string description: Tags for categorizing the agent main: type: string description: Main configuration file name within source directory required: - description - author - tags additionalProperties: false description: Agent metadata including description, author, and tags required: - id - sourcePath - metadata additionalProperties: false description: Request body for installing a custom agent from file system - type: object properties: id: type: string minLength: 1 description: Unique agent identifier (e.g., "database-agent") path: type: string description: >- Optional absolute file path for file-based agents (e.g., "/path/to/agent.yml") required: - id additionalProperties: false description: Agent identifier for switching agents by ID or file path description: Agent installation request responses: '201': description: Agent installed content: application/json: schema: type: object properties: installed: type: boolean enum: - true description: Indicates successful installation id: type: string description: Installed agent ID name: type: string description: Installed agent name type: type: string enum: - builtin - custom description: Type of agent installed required: - installed - id - name - type additionalProperties: false description: Agent installation response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agents/switch: post: summary: Switch Agent description: Switches to a different agent by ID or file path tags: - agents requestBody: content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Unique agent identifier (e.g., "database-agent") path: type: string description: >- Optional absolute file path for file-based agents (e.g., "/path/to/agent.yml") required: - id additionalProperties: false description: Agent identifier for switching agents by ID or file path responses: '200': description: Agent switched content: application/json: schema: type: object properties: switched: type: boolean enum: - true description: Indicates successful agent switch id: type: string description: New active agent ID name: type: string description: New active agent name required: - switched - id - name additionalProperties: false description: Agent switch response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agents/validate-name: post: summary: Validate Agent Name description: Checks if an agent ID conflicts with existing agents tags: - agents requestBody: content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Unique agent identifier (e.g., "database-agent") path: type: string description: >- Optional absolute file path for file-based agents (e.g., "/path/to/agent.yml") required: - id additionalProperties: false description: Agent identifier for switching agents by ID or file path responses: '200': description: Name validation result content: application/json: schema: type: object properties: valid: type: boolean description: Whether the agent name is valid conflict: type: string description: Type of conflict if name is invalid message: type: string description: Validation message required: - valid additionalProperties: false description: Agent name validation result '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agents/uninstall: post: summary: Uninstall Agent description: >- Removes an agent from the system. Custom agents are removed from registry; builtin agents can be reinstalled tags: - agents requestBody: content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Unique agent identifier to uninstall force: type: boolean default: false description: Force uninstall even if agent is currently active required: - id additionalProperties: false description: Request body for uninstalling an agent responses: '200': description: Agent uninstalled content: application/json: schema: type: object properties: uninstalled: type: boolean enum: - true description: Indicates successful uninstallation id: type: string description: Uninstalled agent ID required: - uninstalled - id additionalProperties: false description: Agent uninstallation response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agents/custom/create: post: summary: Create Custom Agent description: Creates a new custom agent from scratch via the UI/API tags: - agents requestBody: content: application/json: schema: type: object properties: id: type: string minLength: 1 pattern: ^[a-z0-9-]+$ description: Unique agent identifier name: type: string minLength: 1 description: Display name for the agent description: type: string minLength: 1 description: One-line description of the agent author: type: string description: Author or organization tags: type: array items: type: string default: [] description: Tags for discovery config: type: object additionalProperties: allOf: - $ref: '#/components/schemas/JsonValue' - $ref: '#/components/schemas/JsonValue' description: Complete agent configuration required: - id - name - description - config additionalProperties: false description: >- Request body for creating a new custom agent with full configuration responses: '201': description: Custom agent created content: application/json: schema: type: object properties: created: type: boolean enum: - true description: Creation success indicator id: type: string description: Agent identifier name: type: string description: Agent name required: - created - id - name additionalProperties: false description: Custom agent creation response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agent/path: get: summary: Get Agent File Path description: Retrieves the file path of the currently active agent configuration tags: - agent responses: '200': description: Agent file path content: application/json: schema: type: object properties: path: type: string description: Absolute path to agent configuration file relativePath: type: string description: Relative path or basename name: type: string description: Agent configuration filename without extension isDefault: type: boolean description: Whether this is the default agent required: - path - relativePath - name - isDefault additionalProperties: false description: Agent file path information '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agent/config: get: summary: Get Agent Configuration description: Retrieves the raw YAML configuration of the currently active agent tags: - agent responses: '200': description: Agent configuration content: application/json: schema: type: object properties: yaml: type: string description: Raw YAML configuration content path: type: string description: Absolute path to configuration file relativePath: type: string description: Relative path or basename lastModified: type: string format: date-time description: Last modification timestamp warnings: type: array items: type: string description: Configuration warnings required: - yaml - path - relativePath - lastModified - warnings additionalProperties: false description: Agent configuration content '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response post: summary: Save Agent Configuration description: Saves and applies YAML agent configuration. Creates backup before saving tags: - agent requestBody: content: application/json: schema: type: object properties: yaml: type: string minLength: 1 description: YAML agent configuration content to save required: - yaml description: Request body for saving agent configuration YAML responses: '200': description: Configuration saved content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Indicates successful save path: type: string description: Path to saved configuration file reloaded: type: boolean description: Whether configuration was reloaded restarted: type: boolean description: Whether agent was restarted changesApplied: type: array items: type: string description: List of changes that were applied message: type: string description: Success message required: - ok - path - reloaded - restarted - changesApplied - message additionalProperties: false description: Configuration save result '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agent/validate: post: summary: Validate Agent Configuration description: Validates YAML agent configuration without saving it tags: - agent requestBody: content: application/json: schema: type: object properties: yaml: type: string description: YAML agent configuration content to validate required: - yaml description: Request body for validating agent configuration YAML responses: '200': description: Validation result content: application/json: schema: type: object properties: valid: type: boolean description: Whether configuration is valid errors: type: array items: type: object properties: line: type: integer description: Line number column: type: integer description: Column number path: type: string description: Configuration path message: type: string description: Error message code: type: string description: Error code required: - message - code additionalProperties: nullable: true description: Configuration validation error description: Validation errors warnings: type: array items: type: object properties: path: type: string description: Configuration path message: type: string description: Warning message code: type: string description: Warning code required: - path - message - code additionalProperties: false description: Configuration validation warning description: Configuration warnings required: - valid - errors - warnings additionalProperties: false description: Configuration validation result '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Resource not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '409': description: Conflict content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/agent/config/export: get: summary: Export Agent Configuration description: Exports the effective agent configuration with sensitive values redacted tags: - agent parameters: - schema: type: string description: Session identifier to export session-specific configuration required: false description: Session identifier to export session-specific configuration name: sessionId in: query responses: '200': description: Exported configuration content: application/x-yaml: schema: type: string /api/queue/{sessionId}: get: summary: Get queued messages description: Returns all messages waiting in the queue for a session tags: - queue parameters: - schema: type: string minLength: 1 description: Session ID required: true description: Session ID name: sessionId in: path responses: '200': description: List of queued messages content: application/json: schema: type: object properties: messages: type: array items: type: object properties: id: type: string description: Unique identifier for the queued message content: type: array items: oneOf: - type: object properties: type: type: string enum: - text description: 'Part type: text' text: type: string description: Text content required: - type - text additionalProperties: false description: Text content part - type: object properties: type: type: string enum: - image description: 'Part type: image' image: type: string description: Base64-encoded image data mimeType: type: string description: MIME type of the image required: - type - image additionalProperties: false description: Image content part - type: object properties: type: type: string enum: - file description: 'Part type: file' data: type: string description: Base64-encoded file data mimeType: type: string description: MIME type of the file filename: type: string description: Optional filename required: - type - data - mimeType additionalProperties: false description: File content part - type: object properties: type: type: string enum: - resource description: 'Part type: resource' uri: type: string description: Canonical resource reference name: type: string description: Display name for the resource mimeType: type: string description: MIME type of the resource kind: type: string enum: - text - image - audio - video - binary description: >- Resource kind for rendering and prompt projection size: type: integer minimum: 0 description: Size in bytes metadata: type: object properties: mtimeMs: type: number minimum: 0 description: mtime in ms source: type: string enum: - filesystem - upload - generated - tool - remote description: How the resource was created additionalProperties: false description: Optional resource metadata required: - type - uri - name - mimeType - kind additionalProperties: false description: Canonical resource reference part - type: object properties: type: type: string enum: - ui-resource description: 'Part type: ui-resource' uri: type: string description: >- URI identifying the UI resource (must start with ui://) mimeType: type: string description: >- MIME type: text/html, text/uri-list, or application/vnd.mcp-ui.remote-dom content: type: string description: Inline HTML content or URL blob: type: string description: >- Base64-encoded content (alternative to content) metadata: type: object properties: title: type: string description: Display title for the UI resource preferredSize: type: object properties: width: type: number description: Preferred width in pixels height: type: number description: Preferred height in pixels required: - width - height additionalProperties: false description: Preferred rendering size additionalProperties: false description: Optional metadata for the UI resource required: - type - uri - mimeType additionalProperties: false description: >- UI Resource content part for MCP-UI interactive components description: >- Message content part (text, image, file, resource, or UI resource) description: Message content parts queuedAt: type: number description: Unix timestamp when message was queued metadata: type: object additionalProperties: true description: Optional metadata kind: type: string enum: - default - background description: Optional queued message kind required: - id - content - queuedAt additionalProperties: false description: A message waiting in the queue description: Queued messages count: type: number description: Number of messages in queue required: - messages - count additionalProperties: false description: Get queue response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Session not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response post: summary: Queue a message description: >- Adds a message to the queue for processing when the session is no longer busy tags: - queue parameters: - schema: type: string minLength: 1 description: Session ID required: true description: Session ID name: sessionId in: path requestBody: content: application/json: schema: type: object properties: content: anyOf: - type: string - type: array items: oneOf: - type: object properties: type: type: string enum: - text description: 'Part type: text' text: type: string description: Text content required: - type - text additionalProperties: false description: Text content part - type: object properties: type: type: string enum: - image description: 'Part type: image' image: type: string description: Base64-encoded image data mimeType: type: string description: MIME type of the image required: - type - image additionalProperties: false description: Image content part - type: object properties: type: type: string enum: - file description: 'Part type: file' data: type: string description: Base64-encoded file data mimeType: type: string description: MIME type of the file filename: type: string description: Optional filename required: - type - data - mimeType additionalProperties: false description: File content part description: Request message content part (text, image, or file) description: >- Message content - string for text, or ContentPart[] for multimodal kind: type: string enum: - default - background description: Optional queued message kind required: - content description: Request body for queueing a message responses: '201': description: Message queued successfully content: application/json: schema: type: object properties: queued: type: boolean enum: - true description: Indicates message was queued id: type: string description: ID of the queued message position: type: number description: Position in the queue (1-based) required: - queued - id - position additionalProperties: false description: Queue message response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Session not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response delete: summary: Clear message queue description: Removes all messages from the queue for a session tags: - queue parameters: - schema: type: string minLength: 1 description: Session ID required: true description: Session ID name: sessionId in: path responses: '200': description: Queue cleared successfully content: application/json: schema: type: object properties: cleared: type: boolean enum: - true description: Indicates queue was cleared count: type: number description: Number of messages that were removed required: - cleared - count additionalProperties: false description: Clear queue response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Session not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/queue/{sessionId}/{messageId}: delete: summary: Remove queued message description: Removes a specific message from the queue tags: - queue parameters: - schema: type: string minLength: 1 description: Session ID required: true description: Session ID name: sessionId in: path - schema: type: string minLength: 1 description: ID of the queued message to remove required: true description: ID of the queued message to remove name: messageId in: path responses: '200': description: Message removed successfully content: application/json: schema: type: object properties: removed: type: boolean enum: - true description: Indicates message was removed id: type: string description: ID of the removed message required: - removed - id additionalProperties: false description: Remove queued message response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Session or message not found content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/openrouter/validate/{modelId}: get: summary: Validate OpenRouter Model description: >- Validates an OpenRouter model ID against the cached model registry. Refreshes cache if stale. tags: - openrouter parameters: - schema: type: string minLength: 1 description: >- OpenRouter model ID to validate (e.g., anthropic/claude-3.5-sonnet) required: true description: OpenRouter model ID to validate (e.g., anthropic/claude-3.5-sonnet) name: modelId in: path responses: '200': description: Validation result content: application/json: schema: type: object properties: valid: type: boolean description: Whether the model ID is valid modelId: type: string description: The model ID that was validated status: type: string enum: - valid - invalid - unknown description: >- Validation status: valid, invalid, or unknown (cache empty) error: type: string description: Error message if invalid info: type: object properties: contextLength: type: number description: Model context length in tokens required: - contextLength description: Model information if valid required: - valid - modelId - status description: Model validation response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/openrouter/refresh-cache: post: summary: Refresh OpenRouter Model Cache description: Forces a refresh of the OpenRouter model registry cache from the API. tags: - openrouter responses: '200': description: Cache refreshed successfully content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Success indicator message: type: string description: Status message required: - ok - message description: OpenRouter cache refresh success response '500': description: Cache refresh failed content: application/json: schema: type: object properties: ok: type: boolean enum: - false description: Failure indicator message: type: string description: Error message required: - ok - message description: OpenRouter cache refresh failure response /api/llm/key/{provider}: get: summary: Get Provider API Key Status description: >- Retrieves the API key status for a provider. Returns a masked key value (e.g., sk-proj...xyz4) for UI display purposes. tags: - llm parameters: - schema: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider identifier required: true description: LLM provider identifier name: provider in: path responses: '200': description: API key status and value content: application/json: schema: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: Provider identifier envVar: type: string description: Environment variable name hasKey: type: boolean description: Whether API key is configured keyValue: type: string description: Masked API key value if configured (e.g., sk-proj...xyz4) required: - provider - envVar - hasKey additionalProperties: false description: API key status response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/llm/key: post: summary: Save Provider API Key description: >- Stores an API key for a provider in .env and makes it available immediately tags: - llm requestBody: content: application/json: schema: type: object properties: provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: LLM provider identifier (e.g., openai, anthropic) apiKey: type: string minLength: 1 description: >- API key for the provider (writeOnly - never returned in responses) writeOnly: true required: - provider - apiKey description: Request body for saving a provider API key responses: '200': description: API key saved content: application/json: schema: type: object properties: ok: type: boolean enum: - true description: Operation success indicator provider: type: string enum: - openai - openai-compatible - anthropic - google - groq - xai - cohere - minimax - glm - openrouter - litellm - glama - vertex - bedrock - local - ollama - dexto-nova description: Provider for which the key was saved envVar: type: string description: Environment variable name where key was stored required: - ok - provider - envVar additionalProperties: false description: API key save response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/tools: get: summary: List All Tools description: Retrieves all available tools from all sources (local and MCP) tags: - tools responses: '200': description: All tools content: application/json: schema: type: object properties: tools: type: array items: type: object properties: id: type: string description: Tool identifier name: type: string description: Tool name description: type: string description: Tool description source: type: string enum: - local - mcp description: Source of the tool (local or mcp) serverName: type: string description: MCP server name (if source is mcp) inputSchema: type: object properties: type: type: string enum: - object description: Schema type, always "object" when present properties: type: object additionalProperties: type: object properties: type: type: string enum: - string - number - integer - boolean - object - array description: Property type description: type: string description: Property description enum: type: array items: anyOf: - type: string - type: number - type: boolean - nullable: true description: Allowed JSON Schema enum value description: Enum values default: type: object additionalProperties: true description: Default value format: type: string description: JSON Schema format hint additionalProperties: nullable: true description: JSON Schema property definition description: Property definitions required: type: array items: type: string description: Required property names additionalProperties: nullable: true description: JSON Schema for tool input parameters _meta: type: object additionalProperties: allOf: - $ref: '#/components/schemas/JsonValue' - $ref: '#/components/schemas/JsonValue' description: >- Optional tool metadata (e.g., MCP Apps UI resource info) required: - id - name - description - source additionalProperties: false description: Tool information description: Array of all available tools totalCount: type: number description: Total number of tools localCount: type: number description: Number of local tools mcpCount: type: number description: Number of MCP tools required: - tools - totalCount - localCount - mcpCount additionalProperties: false description: All available tools from all sources '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/discovery: get: summary: Discover Available Factories and Tools description: >- Returns all available factories (storage, compaction, tools) for the currently active image. tags: - discovery responses: '200': description: Available factories grouped by category content: application/json: schema: type: object properties: blob: type: array items: type: object properties: type: type: string description: Factory type identifier category: type: string enum: - blob - database - compaction - tools description: Factory category metadata: type: object properties: displayName: type: string description: Human-readable display name description: type: string description: Factory description additionalProperties: nullable: true description: Optional metadata about the factory required: - type - category description: Information about a registered factory description: Blob storage factories database: type: array items: type: object properties: type: type: string description: Factory type identifier category: type: string enum: - blob - database - compaction - tools description: Factory category metadata: type: object properties: displayName: type: string description: Human-readable display name description: type: string description: Factory description additionalProperties: nullable: true description: Optional metadata about the factory required: - type - category description: Information about a registered factory description: Database factories compaction: type: array items: type: object properties: type: type: string description: Factory type identifier category: type: string enum: - blob - database - compaction - tools description: Factory category metadata: type: object properties: displayName: type: string description: Human-readable display name description: type: string description: Factory description additionalProperties: nullable: true description: Optional metadata about the factory required: - type - category description: Information about a registered factory description: Compaction strategy factories toolFactories: type: array items: type: object properties: type: type: string description: Factory type identifier category: type: string enum: - blob - database - compaction - tools description: Factory category metadata: type: object properties: displayName: type: string description: Human-readable display name description: type: string description: Factory description additionalProperties: nullable: true description: Optional metadata about the factory required: - type - category description: Information about a registered factory description: Tool factories builtinTools: type: array items: type: object properties: name: type: string description: >- Built-in tool name identifier (e.g., "search_history", "ask_user") description: type: string description: Human-readable description of what the tool does required: - name - description description: Information about a built-in tool description: Built-in tools available for configuration required: - blob - database - compaction - toolFactories - builtinTools description: Discovery response with factories grouped by category '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/models/local: get: summary: List Local Models description: >- Returns all installed local GGUF models from ~/.dexto/models/state.json. These are models downloaded from HuggingFace or manually registered. tags: - models responses: '200': description: List of installed local models content: application/json: schema: type: object properties: models: type: array items: type: object properties: id: type: string description: Model identifier displayName: type: string description: Human-readable model name filePath: type: string description: Absolute path to the GGUF file sizeBytes: type: number description: File size in bytes contextLength: type: number description: Maximum context length in tokens source: type: string enum: - huggingface - manual description: Where the model was downloaded from required: - id - displayName - filePath - sizeBytes description: An installed local GGUF model description: List of installed local models required: - models '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/models/ollama: get: summary: List Ollama Models description: >- Returns available models from the local Ollama server. Returns empty list with available=false if Ollama is not running. tags: - models parameters: - schema: type: string format: uri description: 'Ollama server URL (default: http://localhost:11434)' required: false description: 'Ollama server URL (default: http://localhost:11434)' name: baseURL in: query responses: '200': description: List of Ollama models content: application/json: schema: type: object properties: available: type: boolean description: Whether Ollama server is running version: type: string description: Ollama server version models: type: array items: type: object properties: name: type: string description: Ollama model name (e.g., llama3.2:latest) size: type: number description: Model size in bytes digest: type: string description: Model digest/hash modifiedAt: type: string description: Last modified timestamp required: - name description: An Ollama model description: List of available Ollama models error: type: string description: Error message if Ollama not available required: - available - models '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/models/local/validate: post: summary: Validate GGUF File description: >- Validates that a GGUF file exists and is readable. Used by Web UI to validate custom file paths before saving. tags: - models requestBody: content: application/json: schema: type: object properties: filePath: type: string minLength: 1 description: Absolute path to the GGUF file to validate required: - filePath description: File validation request responses: '200': description: Validation result content: application/json: schema: type: object properties: valid: type: boolean description: Whether the file exists and is readable sizeBytes: type: number description: File size in bytes if valid error: type: string description: Error message if invalid required: - valid description: File validation response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/models/local/{modelId}: delete: summary: Delete Installed Model description: >- Removes an installed local model from state.json. Optionally deletes the GGUF file from disk (default: true). tags: - models parameters: - schema: type: string description: The model ID to delete required: true description: The model ID to delete name: modelId in: path requestBody: required: false content: application/json: schema: type: object properties: deleteFile: type: boolean default: true description: Whether to also delete the GGUF file from disk description: Delete model request options responses: '200': description: Model deleted successfully content: application/json: schema: type: object properties: success: type: boolean description: Whether the deletion was successful modelId: type: string description: The deleted model ID fileDeleted: type: boolean description: Whether the GGUF file was deleted error: type: string description: Error message if deletion failed required: - success - modelId - fileDeleted description: Delete model response '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '404': description: Model not found content: application/json: schema: type: object properties: success: type: boolean description: Whether the deletion was successful modelId: type: string description: The deleted model ID fileDeleted: type: boolean description: Whether the GGUF file was deleted error: type: string description: Error message if deletion failed required: - success - modelId - fileDeleted description: Delete model response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/system-prompt/contributors: get: summary: List System Prompt Contributors description: Lists currently registered system prompt contributors. tags: - config responses: '200': description: Current contributor list content: application/json: schema: type: object properties: contributors: type: array items: type: object properties: id: type: string description: Contributor identifier priority: type: number description: Contributor priority required: - id - priority additionalProperties: false description: System prompt contributor metadata. description: Registered system prompt contributors. required: - contributors additionalProperties: false description: System prompt contributors list response. '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response post: summary: Upsert System Prompt Contributor description: >- Adds or updates a static system prompt contributor. Set enabled=false (or empty content) to remove. tags: - config requestBody: content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Contributor identifier priority: type: number description: Optional priority override enabled: type: boolean description: >- Set false to remove the contributor instead of adding/updating it content: type: string description: Static contributor content (required when enabled). required: - id additionalProperties: false description: System prompt contributor update payload. responses: '200': description: Contributor upsert result content: application/json: schema: type: object properties: id: type: string description: Contributor identifier enabled: type: boolean description: Whether the contributor remains enabled priority: type: number description: Contributor priority replaced: type: boolean description: Whether an existing contributor was replaced removed: type: boolean description: Whether the contributor was removed contentLength: type: number description: Stored content length in characters truncated: type: boolean description: Whether the submitted content was truncated required: - id - enabled additionalProperties: false description: System prompt contributor upsert response. '400': description: Validation or request error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response /api/dexto-auth/status: get: summary: Dexto Auth Status description: >- Returns dexto authentication status. Used by Web UI to check if user can use dexto features. tags: - auth responses: '200': description: Dexto auth status content: application/json: schema: type: object properties: enabled: type: boolean description: Whether dexto auth feature is enabled authenticated: type: boolean description: Whether user is authenticated with dexto canUse: type: boolean description: Whether user can use dexto (authenticated AND has API key) required: - enabled - authenticated - canUse description: Dexto auth status response '500': description: Internal server error content: application/json: schema: type: object properties: name: type: string description: Optional error class name message: type: string description: Human-readable error message code: type: string description: Machine-readable error code scope: type: string description: Domain that produced the error type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Optional error severity for lightweight failures endpoint: type: string description: Request path that failed method: type: string description: HTTP method for the failed request traceId: type: string description: Optional trace identifier recovery: anyOf: - type: string - type: array items: type: string description: Optional recovery guidance context: type: object additionalProperties: true description: Optional structured error context issues: type: array items: type: object properties: code: type: string description: Machine-readable issue code message: type: string description: Human-readable issue message scope: type: string description: Domain that produced the issue type: type: string description: Error type used for HTTP status mapping severity: type: string enum: - error - warning description: Issue severity path: type: array items: anyOf: - type: string - type: number description: Optional location for the issue context: type: object additionalProperties: true description: Optional structured issue context required: - code - message - scope - type - severity additionalProperties: false description: Structured validation or runtime issue description: Validation issues when present errorCount: type: integer minimum: 0 description: Number of errors warningCount: type: integer minimum: 0 description: Number of warnings stack: type: string description: Development-only stack trace required: - message - endpoint - method additionalProperties: false description: Standard API error response