{ "openapi": "3.0.0", "info": { "title": "Dexto API", "version": "1.5.6", "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": "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 internal, custom, 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": {}, "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": { "nullable": 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": { "nullable": true }, "description": "Extension metadata" } }, "required": [ "kind", "file" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data" ], "description": "Part type discriminator" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Structured JSON data" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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": { "nullable": 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": { "nullable": 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": { "nullable": 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": { "nullable": true }, "description": "Extension metadata" } }, "required": [ "kind", "file" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data" ], "description": "Part type discriminator" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Structured JSON data" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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": { "nullable": 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": { "nullable": 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": { "nullable": true }, "description": "Extension metadata" } }, "required": [ "kind", "file" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data" ], "description": "Part type discriminator" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Structured JSON data" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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": { "nullable": 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": { "nullable": true }, "description": "Task artifacts" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Extension metadata" }, "kind": { "type": "string", "enum": [ "task" ], "description": "Object type discriminator" } }, "required": [ "id", "contextId", "status", "kind" ], "description": "A2A Protocol task" } } } } } } }, "/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": { "nullable": 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": { "nullable": true }, "description": "Extension metadata" } }, "required": [ "kind", "file" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data" ], "description": "Part type discriminator" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Structured JSON data" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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": { "nullable": 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": { "nullable": 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": { "nullable": true }, "description": "Extension metadata" } }, "required": [ "kind", "file" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data" ], "description": "Part type discriminator" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Structured JSON data" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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": { "nullable": 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": { "nullable": true }, "description": "Task artifacts" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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" } } } } } } }, "/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": { "nullable": 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": { "nullable": true }, "description": "Extension metadata" } }, "required": [ "kind", "file" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data" ], "description": "Part type discriminator" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Structured JSON data" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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": { "nullable": 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": { "nullable": 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": { "nullable": true }, "description": "Extension metadata" } }, "required": [ "kind", "file" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data" ], "description": "Part type discriminator" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Structured JSON data" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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": { "nullable": 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": { "nullable": true }, "description": "Task artifacts" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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" } } } }, "/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": { "nullable": 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": { "nullable": true }, "description": "Extension metadata" } }, "required": [ "kind", "file" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data" ], "description": "Part type discriminator" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Structured JSON data" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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": { "nullable": 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": { "nullable": 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": { "nullable": true }, "description": "Extension metadata" } }, "required": [ "kind", "file" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data" ], "description": "Part type discriminator" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Structured JSON data" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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": { "nullable": 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": { "nullable": true }, "description": "Task artifacts" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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" } } } }, "/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 } } } } } } }, "/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": "Content type identifier" }, "text": { "type": "string", "description": "Text content" } }, "required": [ "type", "text" ], "description": "Text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ], "description": "Content type identifier" }, "image": { "type": "string", "description": "Base64-encoded image data or URL" }, "mimeType": { "type": "string", "description": "MIME type (e.g., image/png)" } }, "required": [ "type", "image" ], "description": "Image content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ], "description": "Content type identifier" }, "data": { "type": "string", "description": "Base64-encoded file data or URL" }, "mimeType": { "type": "string", "description": "MIME type (e.g., application/pdf)" }, "filename": { "type": "string", "description": "Optional filename" } }, "required": [ "type", "data", "mimeType" ], "description": "File content part" } ], "description": "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 } } } }, "400": { "description": "Validation error" } } } }, "/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": "Content type identifier" }, "text": { "type": "string", "description": "Text content" } }, "required": [ "type", "text" ], "description": "Text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ], "description": "Content type identifier" }, "image": { "type": "string", "description": "Base64-encoded image data or URL" }, "mimeType": { "type": "string", "description": "MIME type (e.g., image/png)" } }, "required": [ "type", "image" ], "description": "Image content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ], "description": "Content type identifier" }, "data": { "type": "string", "description": "Base64-encoded file data or URL" }, "mimeType": { "type": "string", "description": "MIME type (e.g., application/pdf)" }, "filename": { "type": "string", "description": "Optional filename" } }, "required": [ "type", "data", "mimeType" ], "description": "File content part" } ], "description": "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" }, "totalTokens": { "type": "integer", "minimum": 0, "description": "Total tokens used" } }, "additionalProperties": false, "description": "Token usage statistics" }, "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", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "description": "LLM provider" } }, "required": [ "response", "sessionId" ], "additionalProperties": false } } } }, "400": { "description": "Validation error" } } } }, "/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 } } } } } } }, "/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. 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": "Content type identifier" }, "text": { "type": "string", "description": "Text content" } }, "required": [ "type", "text" ], "description": "Text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ], "description": "Content type identifier" }, "image": { "type": "string", "description": "Base64-encoded image data or URL" }, "mimeType": { "type": "string", "description": "MIME type (e.g., image/png)" } }, "required": [ "type", "image" ], "description": "Image content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ], "description": "Content type identifier" }, "data": { "type": "string", "description": "Base64-encoded file data or URL" }, "mimeType": { "type": "string", "description": "MIME type (e.g., application/pdf)" }, "filename": { "type": "string", "description": "Optional filename" } }, "required": [ "type", "data", "mimeType" ], "description": "File content part" } ], "description": "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)" } } } }, "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 } } } }, "400": { "description": "Validation error" } } } }, "/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", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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 }, "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." }, "reasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ], "description": "OpenAI reasoning effort level for reasoning models (o1, o3, codex). Options: 'none', 'minimal', 'low', 'medium' (recommended), 'high', 'xhigh'" }, "hasApiKey": { "type": "boolean", "description": "Whether an API key is configured" }, "displayName": { "type": "string", "description": "Human-readable model display name" } }, "required": [ "provider", "model" ], "additionalProperties": false, "description": "LLM configuration (apiKey omitted for security)" }, "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" } } } } } } }, "/api/llm/catalog": { "get": { "summary": "LLM Catalog", "description": "Providers, models, capabilities, and API key status", "tags": [ "llm" ], "parameters": [ { "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": "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" ], "description": "Filter by supported file type (audio, pdf, or image)" }, "required": false, "description": "Filter by supported file type (audio, pdf, or image)", "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "description": "Provider-level file type support" } }, "required": [ "name", "hasApiKey", "primaryEnvVar", "supportsBaseURL", "models", "supportedFileTypes" ], "additionalProperties": false, "description": "Provider catalog entry with models and capabilities" }, "dexto": { "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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": [ "audio", "pdf", "image" ] }, "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" } } } } } } }, "/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", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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." }, "reasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ], "description": "OpenAI reasoning effort level for reasoning models (o1, o3, codex). Options: 'none', 'minimal', 'low', 'medium' (recommended), 'high', 'xhigh'" } } }, { "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", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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 }, "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." }, "reasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ], "description": "OpenAI reasoning effort level for reasoning models (o1, o3, codex). Options: 'none', 'minimal', 'low', 'medium' (recommended), 'high', 'xhigh'" }, "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" } } } } } } }, "/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" ], "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" }, "reasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] } }, "required": [ "name" ] }, "description": "List of custom models" } }, "required": [ "models" ] } } } } } }, "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" ], "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" }, "reasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] } }, "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" ], "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" }, "reasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh" ] } }, "required": [ "name" ] } }, "required": [ "ok", "model" ] } } } } } } }, "/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" ] } } } }, "404": { "description": "Custom model not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ], "description": "Failure indicator" }, "error": { "type": "string", "description": "Error message" } }, "required": [ "ok", "error" ] } } } } } } }, "/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, openrouter) by resolving to the underlying model capabilities.", "tags": [ "llm" ], "parameters": [ { "schema": { "type": "string", "enum": [ "openai", "openai-compatible", "anthropic", "google", "groq", "xai", "cohere", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "description": "Provider name" }, "model": { "type": "string", "description": "Model name as provided" }, "supportedFileTypes": { "type": "array", "items": { "type": "string", "enum": [ "pdf", "image", "audio" ] }, "description": "File types supported by this model" } }, "required": [ "provider", "model", "supportedFileTypes" ] } } } } } } }, "/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" } }, "required": [ "id", "createdAt", "lastActivity", "messageCount" ], "additionalProperties": false, "description": "Session metadata" }, "description": "Array of session metadata objects" } }, "required": [ "sessions" ], "additionalProperties": false } } } } } }, "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" } }, "required": [ "id", "createdAt", "lastActivity", "messageCount" ], "additionalProperties": false, "description": "Newly created session metadata" } }, "required": [ "session" ], "additionalProperties": false } } } } } } }, "/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" }, "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 } } } } } }, "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 } } } } } }, "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" } }, "required": [ "id", "createdAt", "lastActivity", "messageCount" ], "additionalProperties": false, "description": "Updated session metadata" } }, "required": [ "session" ], "additionalProperties": false } } } } } } }, "/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": [ "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, or UI resource)" } }, { "nullable": true } ], "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" }, "totalTokens": { "type": "integer", "minimum": 0, "description": "Total tokens used" } }, "additionalProperties": false, "description": "Optional token usage accounting" }, "model": { "type": "string", "description": "Model identifier for assistant messages" }, "provider": { "type": "string", "enum": [ "openai", "openai-compatible", "anthropic", "google", "groq", "xai", "cohere", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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 } } } } } } }, "/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 } } } } } } }, "/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" }, "isBusy": { "type": "boolean", "description": "Whether the session is currently processing a message" } }, "required": [ "id", "createdAt", "lastActivity", "messageCount", "isBusy" ], "additionalProperties": false, "description": "Session metadata with processing status" } }, "required": [ "session" ], "additionalProperties": false } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/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 } } } }, "404": { "description": "Session not found (error format handled by middleware)" } } } }, "/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": [ "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, or UI resource)" } }, { "nullable": true } ], "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" }, "totalTokens": { "type": "integer", "minimum": 0, "description": "Total tokens used" } }, "additionalProperties": false, "description": "Optional token usage accounting" }, "model": { "type": "string", "description": "Model identifier for assistant messages" }, "provider": { "type": "string", "enum": [ "openai", "openai-compatible", "anthropic", "google", "groq", "xai", "cohere", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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" } } } } } } }, "/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": [ "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, or UI resource)" } }, { "nullable": true } ], "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" }, "totalTokens": { "type": "integer", "minimum": 0, "description": "Total tokens used" } }, "additionalProperties": false, "description": "Optional token usage accounting" }, "model": { "type": "string", "description": "Model identifier for assistant messages" }, "provider": { "type": "string", "enum": [ "openai", "openai-compatible", "anthropic", "google", "groq", "xai", "cohere", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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" } } } } } } }, "/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" ], "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" } } } } } }, "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" ], "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" } } } } } } }, "/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" } ] }, "description": "Enum values" }, "default": { "nullable": true, "description": "Default value" } }, "description": "JSON Schema property definition" }, "description": "Property definitions" }, "required": { "type": "array", "items": { "type": "string" }, "description": "Required property names" } }, "description": "JSON Schema for tool input parameters" } }, "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" } } } }, "/api/mcp/servers/{serverId}": { "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" } } } }, "/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" } } } }, "/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": { "type": "object", "additionalProperties": { "nullable": true }, "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": { "nullable": 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" } } } }, "/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": "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": { "nullable": true }, "description": "Additional metadata specific to the resource type" } }, "required": [ "uri", "source" ], "additionalProperties": false, "description": "Resource metadata" }, "description": "Array of available resources" } }, "required": [ "success", "resources" ], "additionalProperties": false, "description": "List of resources from MCP server" } } } }, "404": { "description": "Not found" } } } }, "/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": { "nullable": true, "description": "Resource content data" } }, "additionalProperties": false, "description": "Resource content" } }, "required": [ "success", "data" ], "additionalProperties": false, "description": "Resource content response" } } } }, "404": { "description": "Not found" } } } }, "/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": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Creation timestamp (Date or Unix ms)" } }, "required": [ "id", "url", "createdAt" ], "additionalProperties": false, "description": "Registered webhook details" } }, "required": [ "webhook" ], "additionalProperties": false } } } } } }, "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": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Creation timestamp (Date or Unix ms)" } }, "required": [ "id", "url", "createdAt" ], "additionalProperties": false, "description": "Webhook response object" }, "description": "Array of registered webhooks" } }, "required": [ "webhooks" ], "additionalProperties": false } } } } } } }, "/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": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Creation timestamp (Date or Unix ms)" } }, "required": [ "id", "url", "createdAt" ], "additionalProperties": false, "description": "Webhook details" } }, "required": [ "webhook" ], "additionalProperties": false } } } }, "404": { "description": "Not found" } } }, "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" } } } }, "/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" } } } }, "/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" }, "source": { "type": "string", "enum": [ "mcp", "config", "custom" ], "description": "Source of the prompt" }, "metadata": { "type": "object", "additionalProperties": { "nullable": 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" } } } } } } }, "/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" }, "source": { "type": "string", "enum": [ "mcp", "config", "custom" ], "description": "Source of the prompt" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional metadata" } }, "required": [ "name", "source" ], "additionalProperties": false, "description": "Created prompt information" } }, "required": [ "prompt" ], "additionalProperties": false, "description": "Create prompt 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" } }, "required": [ "name" ], "additionalProperties": false, "description": "Prompt definition" } }, "required": [ "definition" ], "additionalProperties": false, "description": "Get prompt definition response" } } } }, "404": { "description": "Prompt not found" } } } }, "/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" } } } }, "/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": { "nullable": true }, "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" } } } } } } }, "/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": { "nullable": 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" } } } } } } }, "/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" } }, "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" } }, "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" } } } } } }, "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" } }, "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" } } } } } } }, "/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" } }, "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" } } } } } }, "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" } }, "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" } }, "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" } } } } } }, "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" } } } } } } }, "/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": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Type-specific metadata" } }, "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" } } } } } } }, "/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" ], "description": "The user decision" }, "formData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Optional form data provided by the user (for elicitation)" }, "rememberChoice": { "type": "boolean", "description": "Whether to remember this choice for future requests" } }, "required": [ "status" ], "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" ], "description": "The final status" } }, "required": [ "ok", "approvalId", "status" ], "description": "Response after processing approval" } } } }, "400": { "description": "Validation error" }, "404": { "description": "Approval request not found or expired" }, "503": { "description": "Approval coordinator unavailable (server not initialized for approvals)" } } } }, "/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" } } } } } } }, "/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)" } } } } } } }, "/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" } ] } } } }, "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" } } } } } } }, "/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" } } } } } } }, "/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" } } } } } } }, "/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" } } } } } } }, "/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": { "nullable": true }, "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 } } } } } } }, "/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" } } } } } } }, "/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", "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" } } } } } }, "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" } } } } } } }, "/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" ] }, "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 warnings" } }, "required": [ "valid", "errors", "warnings" ], "additionalProperties": false } } } } } } }, "/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": [ "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, or UI resource)" }, "description": "Message content parts" }, "queuedAt": { "type": "number", "description": "Unix timestamp when message was queued" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Optional metadata" } }, "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 } } } }, "404": { "description": "Session not found" } } }, "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": "Content type identifier" }, "text": { "type": "string", "description": "Text content" } }, "required": [ "type", "text" ], "description": "Text content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image" ], "description": "Content type identifier" }, "image": { "type": "string", "description": "Base64-encoded image data or URL" }, "mimeType": { "type": "string", "description": "MIME type (e.g., image/png)" } }, "required": [ "type", "image" ], "description": "Image content part" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ], "description": "Content type identifier" }, "data": { "type": "string", "description": "Base64-encoded file data or URL" }, "mimeType": { "type": "string", "description": "MIME type (e.g., application/pdf)" }, "filename": { "type": "string", "description": "Optional filename" } }, "required": [ "type", "data", "mimeType" ], "description": "File content part" } ], "description": "Content part - text, image, or file" } } ], "description": "Message content - string for text, or ContentPart[] for multimodal" } }, "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 } } } }, "404": { "description": "Session not found" } } }, "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 } } } }, "404": { "description": "Session not found" } } } }, "/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 } } } }, "404": { "description": "Session or message not found" } } } }, "/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" } } } } } } }, "/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" ] } } } }, "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" ] } } } } } } }, "/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", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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" } } } } } } }, "/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", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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", "openrouter", "litellm", "glama", "vertex", "bedrock", "local", "ollama", "dexto" ], "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" } } } } } } }, "/api/tools": { "get": { "summary": "List All Tools", "description": "Retrieves all available tools from all sources (internal, custom, and MCP servers)", "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": [ "internal", "custom", "mcp" ], "description": "Source of the tool (internal, custom, 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" } ] }, "description": "Enum values" }, "default": { "nullable": true, "description": "Default value" } }, "description": "JSON Schema property definition" }, "description": "Property definitions" }, "required": { "type": "array", "items": { "type": "string" }, "description": "Required property names" } }, "description": "JSON Schema for tool input parameters" } }, "required": [ "id", "name", "description", "source" ], "additionalProperties": false, "description": "Tool information" }, "description": "Array of all available tools" }, "totalCount": { "type": "number", "description": "Total number of tools" }, "internalCount": { "type": "number", "description": "Number of internal tools" }, "customCount": { "type": "number", "description": "Number of custom tools" }, "mcpCount": { "type": "number", "description": "Number of MCP tools" } }, "required": [ "tools", "totalCount", "internalCount", "customCount", "mcpCount" ], "additionalProperties": false, "description": "All available tools from all sources" } } } } } } }, "/api/discovery": { "get": { "summary": "Discover Available Providers and Tools", "description": "Returns all registered providers (blob storage, database, compaction, custom tools) and available internal tools. Useful for building UIs that need to display configurable options.", "tags": [ "discovery" ], "responses": { "200": { "description": "Available providers grouped by category", "content": { "application/json": { "schema": { "type": "object", "properties": { "blob": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Provider type identifier" }, "category": { "type": "string", "enum": [ "blob", "database", "compaction", "customTools" ], "description": "Provider category" }, "metadata": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Human-readable display name" }, "description": { "type": "string", "description": "Provider description" } }, "description": "Optional metadata about the provider" } }, "required": [ "type", "category" ], "description": "Information about a registered provider" }, "description": "Blob storage providers" }, "database": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Provider type identifier" }, "category": { "type": "string", "enum": [ "blob", "database", "compaction", "customTools" ], "description": "Provider category" }, "metadata": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Human-readable display name" }, "description": { "type": "string", "description": "Provider description" } }, "description": "Optional metadata about the provider" } }, "required": [ "type", "category" ], "description": "Information about a registered provider" }, "description": "Database providers" }, "compaction": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Provider type identifier" }, "category": { "type": "string", "enum": [ "blob", "database", "compaction", "customTools" ], "description": "Provider category" }, "metadata": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Human-readable display name" }, "description": { "type": "string", "description": "Provider description" } }, "description": "Optional metadata about the provider" } }, "required": [ "type", "category" ], "description": "Information about a registered provider" }, "description": "Compaction strategy providers" }, "customTools": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Provider type identifier" }, "category": { "type": "string", "enum": [ "blob", "database", "compaction", "customTools" ], "description": "Provider category" }, "metadata": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Human-readable display name" }, "description": { "type": "string", "description": "Provider description" } }, "description": "Optional metadata about the provider" } }, "required": [ "type", "category" ], "description": "Information about a registered provider" }, "description": "Custom tool providers" }, "internalTools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Internal 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 an internal tool" }, "description": "Internal tools available for configuration" } }, "required": [ "blob", "database", "compaction", "customTools", "internalTools" ], "description": "Discovery response with providers grouped by category" } } } } } } }, "/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" ] } } } } } } }, "/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" ] } } } } } } }, "/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" } } } } } } }, "/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" } } } }, "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" } } } } } } }, "/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" ] } } } } } } } } }