{
  "openapi": "3.0.0",
  "info": {
    "title": "Cherry Studio API",
    "version": "1.0.0",
    "description": "OpenAI-compatible API for Cherry Studio with additional Cherry-specific endpoints",
    "contact": {
      "name": "Cherry Studio",
      "url": "https://github.com/CherryHQ/cherry-studio"
    }
  },
  "servers": [
    {
      "url": "/",
      "description": "Current server"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Use the API key from Cherry Studio settings"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "code": {
                "type": "string"
              }
            }
          }
        }
      },
      "ChatMessage": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": ["system", "user", "assistant", "tool"]
          },
          "content": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "text": {
                      "type": "string"
                    },
                    "image_url": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "function": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "arguments": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": {
            "type": "string",
            "description": "The model to use for completion, in format provider:model-id"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2,
            "default": 1
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1
          },
          "stream": {
            "type": "boolean",
            "default": false
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "function": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "parameters": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "Model": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "enum": ["model"]
          },
          "created": {
            "type": "integer"
          },
          "owned_by": {
            "type": "string"
          }
        }
      },
      "MCPServer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "command": {
            "type": "string"
          },
          "args": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "env": {
            "type": "object"
          },
          "disabled": {
            "type": "boolean"
          }
        }
      },
      "PermissionMode": {
        "type": "string",
        "enum": ["default", "acceptEdits", "bypassPermissions", "plan"],
        "description": "Permission mode for agent operations"
      },
      "AgentType": {
        "type": "string",
        "enum": ["claude-code", "cherry-claw"],
        "description": "Type of agent"
      },
      "AgentConfiguration": {
        "type": "object",
        "properties": {
          "permission_mode": {
            "$ref": "#/components/schemas/PermissionMode",
            "default": "default"
          },
          "max_turns": {
            "type": "integer",
            "default": 10,
            "description": "Maximum number of interaction turns"
          }
        },
        "additionalProperties": true
      },
      "AgentBase": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Agent name"
          },
          "description": {
            "type": "string",
            "description": "Agent description"
          },
          "accessible_paths": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of directory paths the agent can access"
          },
          "instructions": {
            "type": "string",
            "description": "System prompt/instructions"
          },
          "model": {
            "type": "string",
            "description": "Main model ID"
          },
          "plan_model": {
            "type": "string",
            "description": "Optional planning model ID"
          },
          "small_model": {
            "type": "string",
            "description": "Optional small/fast model ID"
          },
          "mcps": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of MCP tool IDs"
          },
          "allowed_tools": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of allowed tool IDs (whitelist)"
          },
          "configuration": {
            "$ref": "#/components/schemas/AgentConfiguration"
          }
        },
        "required": ["model", "accessible_paths"]
      },
      "AgentEntity": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgentBase"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique agent identifier"
              },
              "type": {
                "$ref": "#/components/schemas/AgentType"
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO timestamp of creation"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO timestamp of last update"
              }
            },
            "required": ["id", "type", "created_at", "updated_at"]
          }
        ]
      },
      "CreateAgentRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgentBase"
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "$ref": "#/components/schemas/AgentType"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "description": "Agent name (required)"
              },
              "model": {
                "type": "string",
                "minLength": 1,
                "description": "Main model ID (required)"
              }
            },
            "required": ["type", "name", "model"]
          }
        ]
      },
      "UpdateAgentRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Agent name"
          },
          "description": {
            "type": "string",
            "description": "Agent description"
          },
          "accessible_paths": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of directory paths the agent can access"
          },
          "instructions": {
            "type": "string",
            "description": "System prompt/instructions"
          },
          "model": {
            "type": "string",
            "description": "Main model ID"
          },
          "plan_model": {
            "type": "string",
            "description": "Optional planning model ID"
          },
          "small_model": {
            "type": "string",
            "description": "Optional small/fast model ID"
          },
          "mcps": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of MCP tool IDs"
          },
          "allowed_tools": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of allowed tool IDs (whitelist)"
          },
          "configuration": {
            "$ref": "#/components/schemas/AgentConfiguration"
          }
        },
        "description": "Partial update - all fields are optional"
      },
      "ReplaceAgentRequest": {
        "$ref": "#/components/schemas/AgentBase"
      },
      "SessionEntity": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgentBase"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique session identifier"
              },
              "agent_id": {
                "type": "string",
                "description": "Primary agent ID for the session"
              },
              "agent_type": {
                "$ref": "#/components/schemas/AgentType"
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO timestamp of creation"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "description": "ISO timestamp of last update"
              }
            },
            "required": ["id", "agent_id", "agent_type", "created_at", "updated_at"]
          }
        ]
      },
      "CreateSessionRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgentBase"
          },
          {
            "type": "object",
            "properties": {
              "model": {
                "type": "string",
                "minLength": 1,
                "description": "Main model ID (required)"
              }
            },
            "required": ["model"]
          }
        ]
      },
      "UpdateSessionRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Session name"
          },
          "description": {
            "type": "string",
            "description": "Session description"
          },
          "accessible_paths": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of directory paths the agent can access"
          },
          "instructions": {
            "type": "string",
            "description": "System prompt/instructions"
          },
          "model": {
            "type": "string",
            "description": "Main model ID"
          },
          "plan_model": {
            "type": "string",
            "description": "Optional planning model ID"
          },
          "small_model": {
            "type": "string",
            "description": "Optional small/fast model ID"
          },
          "mcps": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of MCP tool IDs"
          },
          "allowed_tools": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of allowed tool IDs (whitelist)"
          },
          "configuration": {
            "$ref": "#/components/schemas/AgentConfiguration"
          }
        },
        "description": "Partial update - all fields are optional"
      },
      "ReplaceSessionRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgentBase"
          },
          {
            "type": "object",
            "properties": {
              "model": {
                "type": "string",
                "minLength": 1,
                "description": "Main model ID (required)"
              }
            },
            "required": ["model"]
          }
        ]
      },
      "CreateSessionMessageRequest": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "minLength": 1,
            "description": "Message content"
          }
        },
        "required": ["content"]
      },
      "PaginationQuery": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 20,
            "description": "Number of items to return"
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "default": 0,
            "description": "Number of items to skip"
          },
          "status": {
            "type": "string",
            "enum": ["idle", "running", "completed", "failed", "stopped"],
            "description": "Filter by session status"
          }
        }
      },
      "ListAgentsResponse": {
        "type": "object",
        "properties": {
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentEntity"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of agents"
          },
          "limit": {
            "type": "integer",
            "description": "Number of items returned"
          },
          "offset": {
            "type": "integer",
            "description": "Number of items skipped"
          }
        },
        "required": ["agents", "total", "limit", "offset"]
      },
      "ListSessionsResponse": {
        "type": "object",
        "properties": {
          "sessions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SessionEntity"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of sessions"
          },
          "limit": {
            "type": "integer",
            "description": "Number of items returned"
          },
          "offset": {
            "type": "integer",
            "description": "Number of items skipped"
          }
        },
        "required": ["sessions", "total", "limit", "offset"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "description": "Error message"
              },
              "type": {
                "type": "string",
                "description": "Error type"
              },
              "code": {
                "type": "string",
                "description": "Error code"
              }
            },
            "required": ["message", "type", "code"]
          }
        },
        "required": ["error"]
      },
      "KnowledgeBaseEntity": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique knowledge base identifier"
          },
          "name": {
            "type": "string",
            "description": "Knowledge base name"
          },
          "description": {
            "type": "string",
            "description": "Knowledge base description"
          },
          "model": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "provider": {
                "type": "string"
              }
            },
            "description": "Embedding model configuration"
          },
          "dimensions": {
            "type": "integer",
            "description": "Embedding dimensions"
          },
          "chunkSize": {
            "type": "integer",
            "description": "Chunk size for document splitting"
          },
          "chunkOverlap": {
            "type": "integer",
            "description": "Overlap between chunks"
          },
          "documentCount": {
            "type": "integer",
            "description": "Number of documents"
          },
          "version": {
            "type": "integer",
            "description": "Schema version"
          },
          "threshold": {
            "type": "number",
            "description": "Similarity threshold"
          },
          "rerankModel": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "provider": {
                "type": "string"
              }
            },
            "description": "Rerank model configuration"
          },
          "preprocessProvider": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string"
              },
              "provider": {
                "type": "string"
              }
            },
            "description": "Preprocess provider configuration"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Knowledge items"
          },
          "created_at": {
            "type": "number",
            "description": "Creation timestamp"
          },
          "updated_at": {
            "type": "number",
            "description": "Last update timestamp"
          }
        }
      },
      "KnowledgeSearchResult": {
        "type": "object",
        "properties": {
          "pageContent": {
            "type": "string",
            "description": "Document chunk content"
          },
          "score": {
            "type": "number",
            "description": "Similarity score"
          },
          "metadata": {
            "type": "object",
            "description": "Document metadata"
          },
          "knowledge_base_id": {
            "type": "string",
            "description": "Source knowledge base ID"
          },
          "knowledge_base_name": {
            "type": "string",
            "description": "Source knowledge base name"
          }
        }
      },
      "ListKnowledgeBasesResponse": {
        "type": "object",
        "properties": {
          "knowledge_bases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KnowledgeBaseEntity"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of knowledge bases"
          }
        }
      },
      "SearchKnowledgeRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Search query text",
            "minLength": 1,
            "maxLength": 1000
          },
          "knowledge_base_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional list of knowledge base IDs to search. If not provided, searches all knowledge bases."
          },
          "document_count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 5,
            "description": "Maximum number of results to return"
          }
        },
        "required": ["query"]
      },
      "SearchKnowledgeResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "The original search query"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KnowledgeSearchResult"
            }
          },
          "total": {
            "type": "integer",
            "description": "Total number of results"
          },
          "searched_bases": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              }
            },
            "description": "Knowledge bases that were searched"
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Warning messages for partial search failures"
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/agents": {
      "post": {
        "summary": "Create a new agent",
        "description": "Creates a new autonomous agent with the specified configuration and automatically provisions an initial session that mirrors the agent's settings.",
        "tags": ["Agents"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEntity"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List all agents",
        "description": "Retrieves a paginated list of all agents",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Number of agents to return"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Number of agents to skip"
          },
          {
            "in": "query",
            "name": "sortBy",
            "schema": {
              "type": "string",
              "enum": ["created_at", "updated_at", "name", "sort_order"],
              "default": "sort_order"
            },
            "description": "Field to sort by"
          },
          {
            "in": "query",
            "name": "orderBy",
            "schema": {
              "type": "string",
              "enum": ["asc", "desc"],
              "default": "desc"
            },
            "description": "Sort order (asc = ascending, desc = descending). Defaults to asc when sortBy is sort_order."
          }
        ],
        "responses": {
          "200": {
            "description": "List of agents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AgentEntity"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of agents"
                    },
                    "limit": {
                      "type": "integer",
                      "description": "Number of agents returned"
                    },
                    "offset": {
                      "type": "integer",
                      "description": "Number of agents skipped"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/{agentId}": {
      "get": {
        "summary": "Get agent by ID",
        "description": "Retrieves a specific agent by its ID",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEntity"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update agent",
        "description": "Updates an existing agent with the provided data",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEntity"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Partially update agent",
        "description": "Partially updates an existing agent with only the provided fields",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Agent name"
                  },
                  "description": {
                    "type": "string",
                    "description": "Agent description"
                  },
                  "avatar": {
                    "type": "string",
                    "description": "Agent avatar URL"
                  },
                  "instructions": {
                    "type": "string",
                    "description": "System prompt/instructions"
                  },
                  "model": {
                    "type": "string",
                    "description": "Main model ID"
                  },
                  "plan_model": {
                    "type": "string",
                    "description": "Optional planning model ID"
                  },
                  "small_model": {
                    "type": "string",
                    "description": "Optional small/fast model ID"
                  },
                  "tools": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tools"
                  },
                  "mcps": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "MCP tool IDs"
                  },
                  "knowledges": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Knowledge base IDs"
                  },
                  "configuration": {
                    "type": "object",
                    "description": "Extensible settings"
                  },
                  "accessible_paths": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Accessible directory paths"
                  },
                  "permission_mode": {
                    "type": "string",
                    "enum": ["readOnly", "acceptEdits", "bypassPermissions"],
                    "description": "Permission mode"
                  },
                  "max_steps": {
                    "type": "integer",
                    "description": "Maximum steps the agent can take"
                  }
                },
                "description": "Only include the fields you want to update"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEntity"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete agent",
        "description": "Deletes an agent and all associated sessions and logs",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "responses": {
          "204": {
            "description": "Agent deleted successfully"
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/reorder": {
      "put": {
        "summary": "Reorder agents",
        "description": "Sets the display order of agents based on the provided array of agent IDs",
        "tags": ["Agents"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ordered_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Array of agent IDs in the desired display order"
                  }
                },
                "required": ["ordered_ids"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agents reordered successfully"
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/agents": {
      "post": {
        "summary": "Create a new agent",
        "tags": ["Agents"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEntity"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List all agents with pagination",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Number of agents to return"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Number of agents to skip"
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": ["idle", "running", "completed", "failed", "stopped"]
            },
            "description": "Filter by agent status"
          }
        ],
        "responses": {
          "200": {
            "description": "List of agents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListAgentsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{agentId}": {
      "get": {
        "summary": "Get agent by ID",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEntity"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Replace agent (full update)",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReplaceAgentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEntity"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update agent (partial update)",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAgentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEntity"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete agent",
        "tags": ["Agents"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "responses": {
          "204": {
            "description": "Agent deleted successfully"
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{agentId}/sessions": {
      "post": {
        "summary": "Create a new session for an agent",
        "tags": ["Sessions"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSessionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Session created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionEntity"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List sessions for an agent",
        "tags": ["Sessions"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Number of sessions to return"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Number of sessions to skip"
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": ["idle", "running", "completed", "failed", "stopped"]
            },
            "description": "Filter by session status"
          }
        ],
        "responses": {
          "200": {
            "description": "List of sessions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListSessionsResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{agentId}/sessions/reorder": {
      "put": {
        "summary": "Reorder sessions for an agent",
        "tags": ["Sessions"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ordered_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Array of session IDs in desired order"
                  }
                },
                "required": ["ordered_ids"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sessions reordered successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{agentId}/sessions/{sessionId}": {
      "get": {
        "summary": "Get session by ID",
        "tags": ["Sessions"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          },
          {
            "in": "path",
            "name": "sessionId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Session ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Session details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionEntity"
                }
              }
            }
          },
          "404": {
            "description": "Agent or session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Replace session (full update)",
        "tags": ["Sessions"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          },
          {
            "in": "path",
            "name": "sessionId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Session ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReplaceSessionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionEntity"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent or session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update session (partial update)",
        "tags": ["Sessions"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          },
          {
            "in": "path",
            "name": "sessionId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Session ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSessionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionEntity"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent or session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete session",
        "tags": ["Sessions"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          },
          {
            "in": "path",
            "name": "sessionId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Session ID"
          }
        ],
        "responses": {
          "204": {
            "description": "Session deleted successfully"
          },
          "404": {
            "description": "Agent or session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{agentId}/sessions/{sessionId}/messages": {
      "post": {
        "summary": "Create a new message in a session",
        "tags": ["Messages"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          },
          {
            "in": "path",
            "name": "sessionId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Session ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSessionMessageRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number",
                      "description": "Message ID"
                    },
                    "session_id": {
                      "type": "string",
                      "description": "Session ID"
                    },
                    "role": {
                      "type": "string",
                      "enum": ["assistant", "user", "system", "tool"],
                      "description": "Message role"
                    },
                    "content": {
                      "type": "object",
                      "description": "Message content (AI SDK format)"
                    },
                    "agent_session_id": {
                      "type": "string",
                      "description": "Agent session ID for resuming"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "Additional metadata"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent or session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{agentId}/sessions/{sessionId}/messages/{messageId}": {
      "delete": {
        "summary": "Delete a message from a session",
        "tags": ["Messages"],
        "parameters": [
          {
            "in": "path",
            "name": "agentId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Agent ID"
          },
          {
            "in": "path",
            "name": "sessionId",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Session ID"
          },
          {
            "in": "path",
            "name": "messageId",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Message ID"
          }
        ],
        "responses": {
          "204": {
            "description": "Message deleted successfully"
          },
          "404": {
            "description": "Agent, session, or message not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "summary": "Create chat completion",
        "description": "Create a chat completion response, compatible with OpenAI API",
        "tags": ["Chat"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chat completion response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "object": {
                      "type": "string",
                      "example": "chat.completion"
                    },
                    "created": {
                      "type": "integer"
                    },
                    "model": {
                      "type": "string"
                    },
                    "choices": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": {
                            "type": "integer"
                          },
                          "message": {
                            "$ref": "#/components/schemas/ChatMessage"
                          },
                          "finish_reason": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "prompt_tokens": {
                          "type": "integer"
                        },
                        "completion_tokens": {
                          "type": "integer"
                        },
                        "total_tokens": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-sent events stream (when stream=true)"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/knowledge-bases": {
      "get": {
        "summary": "List all knowledge bases",
        "description": "Returns a list of all configured knowledge bases",
        "tags": ["Knowledge"],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Number of knowledge bases to return"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Number of knowledge bases to skip"
          }
        ],
        "responses": {
          "200": {
            "description": "List of knowledge bases",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListKnowledgeBasesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable (Redux store not accessible)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/knowledge-bases/{id}": {
      "get": {
        "summary": "Get a knowledge base by ID",
        "tags": ["Knowledge"],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Knowledge base ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Knowledge base details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeBaseEntity"
                }
              }
            }
          },
          "404": {
            "description": "Knowledge base not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable (Redux store not accessible)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/knowledge-bases/search": {
      "post": {
        "summary": "Search knowledge bases",
        "description": "Search across one or more knowledge bases and retrieve relevant document chunks.\n\nEach result includes:\n- `pageContent`: The text content of the matching chunk\n- `score`: Similarity score (higher = more relevant)\n- `metadata`: Additional information about the source document\n- `knowledge_base_id` & `knowledge_base_name`: Source of the result\n\nResults are sorted by relevance score in descending order.\n",
        "tags": ["Knowledge"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchKnowledgeRequest"
              },
              "example": {
                "query": "How do I configure Ollama embedding?",
                "knowledge_base_ids": ["kb-uuid-1", "kb-uuid-2"],
                "document_count": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchKnowledgeResponse"
                },
                "example": {
                  "query": "Ollama embedding config",
                  "results": [
                    {
                      "pageContent": "To use Ollama embeddings, set the base URL to http://localhost:11434",
                      "score": 0.89,
                      "metadata": {
                        "source": "/path/to/doc.md",
                        "type": "file"
                      },
                      "knowledge_base_id": "kb-uuid-1",
                      "knowledge_base_name": "My Docs"
                    }
                  ],
                  "total": 1,
                  "searched_bases": [
                    {
                      "id": "kb-uuid-1",
                      "name": "My Docs"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "All knowledge base searches failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable (Redux store not accessible)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mcps": {
      "get": {
        "summary": "List MCP servers",
        "description": "Get a list of all configured Model Context Protocol servers",
        "tags": ["MCP"],
        "responses": {
          "200": {
            "description": "List of MCP servers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MCPServer"
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "$ref": "#/components/schemas/Error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/mcps/{server_id}": {
      "get": {
        "summary": "Get MCP server info",
        "description": "Get detailed information about a specific MCP server",
        "tags": ["MCP"],
        "parameters": [
          {
            "in": "path",
            "name": "server_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "MCP server ID"
          }
        ],
        "responses": {
          "200": {
            "description": "MCP server information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/MCPServer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "MCP server not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "$ref": "#/components/schemas/Error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/mcps/{server_id}/mcp": {
      "post": {
        "summary": "MCP protocol proxy",
        "description": "Proxy endpoint for Model Context Protocol communication with a specific MCP server. Accepts all HTTP methods (GET, POST, DELETE, etc.).",
        "tags": ["MCP"],
        "parameters": [
          {
            "in": "path",
            "name": "server_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "MCP server ID"
          }
        ],
        "requestBody": {
          "description": "MCP protocol request body (JSON-RPC format)",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP protocol response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "MCP server not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "$ref": "#/components/schemas/Error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "summary": "Create message",
        "description": "Create a message response using Anthropic's API format",
        "tags": ["Messages"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "max_tokens", "messages"],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Model ID in format \"provider:model_id\"",
                    "example": "my-anthropic:claude-3-5-sonnet-20241022"
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Maximum number of tokens to generate",
                    "example": 1024
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": ["user", "assistant"]
                        },
                        "content": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "array"
                            }
                          ]
                        }
                      }
                    }
                  },
                  "system": {
                    "type": "string",
                    "description": "System message"
                  },
                  "temperature": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Sampling temperature"
                  },
                  "top_p": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Nucleus sampling"
                  },
                  "top_k": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Top-k sampling"
                  },
                  "stream": {
                    "type": "boolean",
                    "description": "Whether to stream the response"
                  },
                  "tools": {
                    "type": "array",
                    "description": "Available tools for the model"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "example": "message"
                    },
                    "role": {
                      "type": "string",
                      "example": "assistant"
                    },
                    "content": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "model": {
                      "type": "string"
                    },
                    "stop_reason": {
                      "type": "string"
                    },
                    "stop_sequence": {
                      "type": "string"
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "input_tokens": {
                          "type": "integer"
                        },
                        "output_tokens": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-sent events stream (when stream=true)"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "example": "error"
                    },
                    "error": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/{provider_id}/v1/messages": {
      "post": {
        "summary": "Create message with provider in path",
        "description": "Create a message response using provider ID from URL path",
        "tags": ["Messages"],
        "parameters": [
          {
            "in": "path",
            "name": "provider_id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Provider ID (e.g., \"my-anthropic\")",
            "example": "my-anthropic"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "max_tokens", "messages"],
                "properties": {
                  "model": {
                    "type": "string",
                    "description": "Model ID without provider prefix",
                    "example": "claude-3-5-sonnet-20241022"
                  },
                  "max_tokens": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Maximum number of tokens to generate",
                    "example": 1024
                  },
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": ["user", "assistant"]
                        },
                        "content": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "array"
                            }
                          ]
                        }
                      }
                    }
                  },
                  "system": {
                    "type": "string",
                    "description": "System message"
                  },
                  "temperature": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Sampling temperature"
                  },
                  "top_p": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1,
                    "description": "Nucleus sampling"
                  },
                  "top_k": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Top-k sampling"
                  },
                  "stream": {
                    "type": "boolean",
                    "description": "Whether to stream the response"
                  },
                  "tools": {
                    "type": "array",
                    "description": "Available tools for the model"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "example": "message"
                    },
                    "role": {
                      "type": "string",
                      "example": "assistant"
                    },
                    "content": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "model": {
                      "type": "string"
                    },
                    "stop_reason": {
                      "type": "string"
                    },
                    "stop_sequence": {
                      "type": "string"
                    },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "input_tokens": {
                          "type": "integer"
                        },
                        "output_tokens": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-sent events stream (when stream=true)"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/v1/models": {
      "get": {
        "summary": "List available models",
        "description": "Returns a list of available AI models from all configured providers with optional filtering",
        "tags": ["Models"],
        "parameters": [
          {
            "in": "query",
            "name": "providerType",
            "schema": {
              "type": "string",
              "enum": ["openai", "openai-response", "anthropic", "gemini"]
            },
            "description": "Filter models by provider type"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Pagination offset"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Maximum number of models to return"
          }
        ],
        "responses": {
          "200": {
            "description": "List of available models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "example": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total number of models (when using pagination)"
                    },
                    "offset": {
                      "type": "integer",
                      "description": "Current offset (when using pagination)"
                    },
                    "limit": {
                      "type": "integer",
                      "description": "Current limit (when using pagination)"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health check endpoint",
        "description": "Check server status (no authentication required)",
        "tags": ["Health"],
        "security": [],
        "responses": {
          "200": {
            "description": "Server is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.0"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/": {
      "get": {
        "summary": "API information",
        "description": "Get basic API information and available endpoints",
        "tags": ["General"],
        "security": [],
        "responses": {
          "200": {
            "description": "API information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "Cherry Studio API"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.0"
                    },
                    "endpoints": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": []
}
