swagger.json
Rama main · réplica de lectura del repositorio original.
{
"openapi": "3.0.0",
"info": {
"title": "Scalytics Copilot",
"version": "4.0.1",
"description": "API for Scalytics Copilot"
},
"servers": [
{
"url": "/api",
"description": "API server"
}
],
"components": {
"schemas": {
"ApiResponseSuccessList": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Operation successful"
},
"count": {
"type": "integer",
"example": 1
},
"total": {
"type": "integer",
"example": 10
},
"data": {
"type": "array",
"items": {
"type": "object"
}
}
}
},
"ApiResponseSuccessObject": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Operation successful"
},
"data": {
"type": "object"
}
}
},
"ApiResponseError": {
"type": "object",
"required": [
"success",
"message"
],
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Error message description"
}
}
},
"Model": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"model_path": {
"type": "string",
"nullable": true
},
"context_window": {
"type": "integer",
"nullable": true
},
"is_active": {
"type": "boolean"
},
"is_primary": {
"type": "boolean",
"nullable": true
},
"external_provider_id": {
"type": "integer",
"nullable": true
},
"external_model_id": {
"type": "string",
"nullable": true
},
"embedding_dimension": {
"type": "integer",
"nullable": true
},
"provider_name": {
"type": "string",
"nullable": true
},
"can_use": {
"type": "boolean",
"description": "Indicates if the current user can use this model based on keys/settings"
},
"model_family": {
"type": "string",
"nullable": true
},
"prompt_format_type": {
"type": "string",
"nullable": true
}
}
},
"ApiKey": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"provider_id": {
"type": "integer"
},
"provider_name": {
"type": "string"
},
"key_name": {
"type": "string"
},
"is_encrypted": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
},
"is_global": {
"type": "boolean"
},
"user_id": {
"type": "integer",
"nullable": true
},
"extra_config": {
"type": "string",
"nullable": true,
"description": "JSON string for extra config like CX ID"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"Chat": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"user_id": {
"type": "integer"
},
"model_id": {
"type": "integer"
},
"title": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"Message": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"chat_id": {
"type": "integer"
},
"role": {
"type": "string",
"enum": [
"user",
"assistant",
"system"
]
},
"content": {
"type": "string"
},
"tokens": {
"type": "integer",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
},
"AgentCapability": {
"type": "object",
"properties": {
"context_window": {
"type": "integer",
"nullable": true
},
"supports_functions": {
"type": "boolean",
"nullable": true
},
"supports_vision": {
"type": "boolean",
"nullable": true
},
"supports_tools": {
"type": "boolean",
"nullable": true
},
"tools": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
}
},
"Agent": {
"allOf": [
{
"$ref": "#/components/schemas/Model"
},
{
"type": "object",
"properties": {
"capabilities": {
"$ref": "#/components/schemas/AgentCapability",
"nullable": true
},
"is_agent": {
"type": "boolean",
"example": true
},
"supported_tools": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
}
}
]
},
"Tool": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"input_schema": {
"type": "object",
"description": "JSON schema for input arguments"
},
"output_schema": {
"type": "object",
"description": "JSON schema for output"
},
"serverId": {
"type": "integer",
"description": "ID of the server providing the tool"
},
"serverName": {
"type": "string",
"description": "Name of the server providing the tool"
}
}
},
"McpServer": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"connection_type": {
"type": "string",
"enum": [
"command",
"websocket",
"stdio"
]
},
"connection_details": {
"type": "string",
"description": "JSON string"
},
"is_active": {
"type": "boolean"
},
"status": {
"type": "string",
"enum": [
"connecting",
"connected",
"disconnected",
"error"
]
},
"last_seen": {
"type": "string",
"format": "date-time",
"nullable": true
},
"last_error": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"responses": {
"UnauthorizedError": {
"description": "API key is missing or invalid / Authentication failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
},
"ForbiddenError": {
"description": "User does not have permission for this action",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
},
"NotFoundError": {
"description": "The requested resource was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
},
"BadRequestError": {
"description": "Invalid input parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
},
"ServerError": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiResponseError"
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/api/agents": {
"get": {
"summary": "List available MCP agents",
"tags": [
"Agents"
],
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "A list of active MCP agents with capabilities.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"count": {
"type": "integer"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/agents/tools": {
"get": {
"summary": "List available MCP tools",
"tags": [
"Agents"
],
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "A list of available MCP tools.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"count": {
"type": "integer"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Tool"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/agents/{agentId}/capabilities": {
"get": {
"summary": "Get capabilities for a specific MCP agent",
"tags": [
"Agents"
],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "agentId",
"required": true,
"schema": {
"type": "integer"
},
"description": "The ID of the agent (model ID)."
}
],
"responses": {
"200": {
"description": "Agent details and capabilities.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"404": {
"$ref": "#/components/responses/NotFoundError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/agents/chat": {
"post": {
"summary": "Start a new chat session with an MCP agent",
"tags": [
"Agents"
],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agentIds": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Array of agent IDs (model IDs) to use, first is primary."
},
"title": {
"type": "string",
"description": "Optional title for the new chat."
}
},
"required": [
"agentIds"
]
}
}
}
},
"responses": {
"201": {
"description": "Agent chat created successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"$ref": "#/components/schemas/Chat"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"404": {
"$ref": "#/components/responses/NotFoundError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/agents/deep-search": {
"post": {
"summary": "Initiate the Scalytics Deep Search workflow",
"tags": [
"Agents"
],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The user's search query."
},
"sources": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of sources (ddg, google, bing). Defaults to ['ddg']."
},
"externalModelId": {
"type": "integer",
"description": "ID of the external model for analysis."
},
"localModelId": {
"type": "integer",
"description": "ID of the local model for analysis."
},
"title": {
"type": "string",
"description": "Optional title for the new chat."
},
"fileIds": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Optional array of uploaded file IDs to include in context."
}
},
"required": [
"externalModelId",
"localModelId"
]
}
}
}
},
"responses": {
"201": {
"description": "Deep search chat created and workflow initiated. Returns chat ID and initial message.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"chatId": {
"type": "integer"
},
"initialMessage": {
"$ref": "#/components/schemas/Message"
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/admin/mcp-servers": {
"get": {
"summary": "Get all registered MCP servers",
"tags": [
"MCP Servers"
],
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "List of MCP servers.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponseSuccessList"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/McpServer"
}
}
}
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
},
"post": {
"summary": "Add a new MCP server registration",
"tags": [
"MCP Servers"
],
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Unique name for the server."
},
"description": {
"type": "string",
"description": "Optional description."
},
"connection_type": {
"type": "string",
"enum": [
"command",
"websocket",
"stdio"
],
"description": "How the backend connects to the server."
},
"connection_details": {
"type": "string",
"description": "JSON string containing connection details based on connection_type. See documentation for expected format per type."
}
},
"required": [
"name",
"connection_type",
"connection_details"
]
}
}
}
},
"responses": {
"201": {
"description": "Server registered successfully. Returns server details and the generated API key (show once).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"apiKey": {
"type": "string",
"description": "Plain text API key - store securely!"
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
},
"/api/admin/mcp-servers/{id}": {
"get": {
"summary": "Get details of a specific MCP server",
"tags": [
"MCP Servers"
],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
},
"description": "ID of the MCP server."
}
],
"responses": {
"200": {
"description": "MCP server details.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponseSuccessObject"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/McpServer"
}
}
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/NotFoundError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
},
"put": {
"summary": "Update an MCP server registration",
"tags": [
"MCP Servers"
],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
},
"description": "ID of the MCP server to update."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"connection_type": {
"type": "string",
"enum": [
"command",
"websocket",
"stdio"
]
},
"connection_details": {
"type": "string",
"description": "JSON string"
},
"is_active": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "MCP server updated successfully.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ApiResponseSuccessObject"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/McpServer"
}
}
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequestError"
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/NotFoundError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
},
"delete": {
"summary": "Delete an MCP server registration",
"tags": [
"MCP Servers"
],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
},
"description": "ID of the MCP server to delete."
}
],
"responses": {
"200": {
"description": "MCP server deleted successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "MCP Server deleted successfully."
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedError"
},
"403": {
"$ref": "#/components/responses/ForbiddenError"
},
"404": {
"$ref": "#/components/responses/NotFoundError"
},
"500": {
"$ref": "#/components/responses/ServerError"
}
}
}
}
},
"tags": [
{
"name": "MCP Servers",
"description": "Management of external MCP server registrations (Admin only)"
}
]
}