{
  "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)"
    }
  ]
}