openapi.yaml

openapi: 3.0.3
info:
  title: HelixAgent AI Platform API
  description: |
    Comprehensive API for AI-powered completions with multi-provider support,
    ensemble reasoning, Cognee AI enhancement, and advanced monitoring capabilities.
  version: 1.0.0
  contact:
    name: HelixAgent Support
    email: support@helixagent.ai
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.helixagent.ai/v1
    description: Production server
  - url: http://localhost:7061/v1
    description: Development server

security:
  - bearerAuth: []

paths:
  /health:
    get:
      summary: Basic health check
      description: Returns basic health status of the API
      operationId: healthCheck
      tags:
        - Monitoring
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy

  /v1/health:
    get:
      summary: Enhanced health check
      description: Returns detailed health status including provider health
      operationId: enhancedHealthCheck
      tags:
        - Monitoring
      security: []
      responses:
        '200':
          description: Service health details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedHealthResponse'

  /metrics:
    get:
      summary: Prometheus metrics
      description: Returns Prometheus-formatted metrics for monitoring
      operationId: getMetrics
      tags:
        - Monitoring
      security: []
      responses:
        '200':
          description: Prometheus metrics
          content:
            text/plain:
              schema:
                type: string

  /v1/auth/register:
    post:
      summary: Register new user
      description: Creates a new user account
      operationId: registerUser
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: User already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/login:
    post:
      summary: User login
      description: Authenticates user and returns JWT token
      operationId: loginUser
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/refresh:
    post:
      summary: Refresh token
      description: Refreshes the JWT token
      operationId: refreshToken
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/auth/logout:
    post:
      summary: User logout
      description: Invalidates the current JWT token
      operationId: logoutUser
      tags:
        - Authentication
      responses:
        '200':
          description: Logout successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Logged out successfully

  /v1/auth/me:
    get:
      summary: Get current user info
      description: Returns information about the authenticated user
      operationId: getCurrentUser
      tags:
        - Authentication
      responses:
        '200':
          description: User info retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/models:
    get:
      summary: List available models
      description: Returns a list of available LLM models
      operationId: listModels
      tags:
        - Models
      security: []
      responses:
        '200':
          description: Models list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsResponse'

  /v1/providers:
    get:
      summary: List providers
      description: Returns a list of available LLM providers with their capabilities
      operationId: listProviders
      tags:
        - Providers
      responses:
        '200':
          description: Providers list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvidersResponse'

  /v1/providers/{name}/health:
    get:
      summary: Get provider health
      description: Returns health status for a specific provider
      operationId: getProviderHealth
      tags:
        - Providers
      parameters:
        - name: name
          in: path
          required: true
          description: Provider name
          schema:
            type: string
            enum: [claude, deepseek, gemini, qwen, zai, ollama, openrouter]
      responses:
        '200':
          description: Provider is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderHealthResponse'
        '404':
          description: Provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Provider is unhealthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderHealthResponse'

  /v1/completions:
    post:
      summary: Create completion
      description: Creates a completion using the specified model
      operationId: createCompletion
      tags:
        - Completions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: Completion created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompletionResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/completions/stream:
    post:
      summary: Create streaming completion
      description: Creates a streaming completion using Server-Sent Events
      operationId: createCompletionStream
      tags:
        - Completions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: Streaming completion started
          content:
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/chat/completions:
    post:
      summary: Create chat completion
      description: Creates a chat completion with message history
      operationId: createChatCompletion
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Chat completion created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/chat/completions/stream:
    post:
      summary: Create streaming chat completion
      description: Creates a streaming chat completion using Server-Sent Events
      operationId: createChatCompletionStream
      tags:
        - Chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Streaming chat completion started
          content:
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/ensemble/completions:
    post:
      summary: Create ensemble completion
      description: Creates a completion using ensemble of multiple LLM providers
      operationId: createEnsembleCompletion
      tags:
        - Ensemble
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnsembleCompletionRequest'
      responses:
        '200':
          description: Ensemble completion created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnsembleCompletionResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/cognee/visualize:
    get:
      summary: Visualize knowledge graph
      description: Returns a visualization of the Cognee knowledge graph
      operationId: visualizeGraph
      tags:
        - Cognee
      responses:
        '200':
          description: Graph visualization data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphVisualization'

  /v1/cognee/datasets:
    get:
      summary: List Cognee datasets
      description: Returns a list of available Cognee datasets
      operationId: listDatasets
      tags:
        - Cognee
      responses:
        '200':
          description: Datasets list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetsResponse'

  /v1/models/metadata:
    get:
      summary: List model metadata
      description: Returns metadata for all available models from Models.dev
      operationId: listModelMetadata
      tags:
        - Models
      security: []
      parameters:
        - name: capability
          in: query
          description: Filter by capability
          schema:
            type: string
        - name: provider
          in: query
          description: Filter by provider
          schema:
            type: string
      responses:
        '200':
          description: Model metadata list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelMetadataListResponse'

  /v1/models/metadata/{id}:
    get:
      summary: Get model metadata
      description: Returns detailed metadata for a specific model
      operationId: getModelMetadata
      tags:
        - Models
      security: []
      parameters:
        - name: id
          in: path
          required: true
          description: Model ID
          schema:
            type: string
      responses:
        '200':
          description: Model metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelMetadata'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/models/metadata/{id}/benchmarks:
    get:
      summary: Get model benchmarks
      description: Returns benchmark data for a specific model
      operationId: getModelBenchmarks
      tags:
        - Models
      security: []
      parameters:
        - name: id
          in: path
          required: true
          description: Model ID
          schema:
            type: string
      responses:
        '200':
          description: Model benchmarks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelBenchmarks'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/models/metadata/compare:
    get:
      summary: Compare models
      description: Compares multiple models side by side
      operationId: compareModels
      tags:
        - Models
      security: []
      parameters:
        - name: models
          in: query
          description: Comma-separated list of model IDs to compare
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Model comparison
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelComparison'

  /v1/admin/health/all:
    get:
      summary: Get all provider health
      description: Returns health status for all providers (admin only)
      operationId: getAllProviderHealth
      tags:
        - Admin
      responses:
        '200':
          description: All provider health
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllProviderHealthResponse'
        '403':
          description: Forbidden - Admin access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/admin/models/metadata/refresh:
    post:
      summary: Refresh model metadata
      description: Triggers a refresh of model metadata from Models.dev (admin only)
      operationId: refreshModelMetadata
      tags:
        - Admin
      responses:
        '200':
          description: Refresh initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Refresh initiated
                  taskId:
                    type: string
        '403':
          description: Forbidden - Admin access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/admin/models/metadata/refresh/status:
    get:
      summary: Get refresh status
      description: Returns the status of the model metadata refresh task (admin only)
      operationId: getRefreshStatus
      tags:
        - Admin
      responses:
        '200':
          description: Refresh status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshStatus'
        '403':
          description: Forbidden - Admin access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/debates:
    post:
      summary: Create a new debate
      description: Initiates a new AI debate with specified participants and configuration
      operationId: createDebate
      tags:
        - Debates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DebateRequest'
      responses:
        '201':
          description: Debate created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebateResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/debates/{debateId}:
    get:
      summary: Get debate details
      description: Retrieves comprehensive information about a specific debate
      operationId: getDebate
      tags:
        - Debates
      parameters:
        - name: debateId
          in: path
          required: true
          description: Unique identifier for the debate
          schema:
            type: string
            pattern: '^[a-zA-Z0-9-]+$'
      responses:
        '200':
          description: Debate details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebateDetails'
        '404':
          description: Debate not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete a debate
      description: Removes a debate and all associated data
      operationId: deleteDebate
      tags:
        - Debates
      parameters:
        - name: debateId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Debate deleted successfully
        '404':
          description: Debate not found

  /v1/debates/{debateId}/status:
    get:
      summary: Get debate status
      description: Returns the current status of a debate
      operationId: getDebateStatus
      tags:
        - Debates
      parameters:
        - name: debateId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Debate status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebateStatus'

  /v1/debates/{debateId}/results:
    get:
      summary: Get debate results
      description: Returns the final results of a completed debate
      operationId: getDebateResults
      tags:
        - Debates
      parameters:
        - name: debateId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Debate results retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebateResult'

  /v1/sessions:
    post:
      summary: Create a new session
      description: Creates a new conversation session
      operationId: createSession
      tags:
        - Sessions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                config:
                  type: object
      responses:
        '201':
          description: Session created
    get:
      summary: List all sessions
      description: Returns all active sessions
      operationId: listSessions
      tags:
        - Sessions
      responses:
        '200':
          description: Sessions list

  /v1/sessions/{id}:
    get:
      summary: Get session details
      description: Returns details of a specific session
      operationId: getSession
      tags:
        - Sessions
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session details
    delete:
      summary: Terminate session
      description: Terminates and removes a session
      operationId: terminateSession
      tags:
        - Sessions
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session terminated

  /v1/lsp/servers:
    get:
      summary: List LSP servers
      description: Returns all configured Language Server Protocol servers
      operationId: listLSPServers
      tags:
        - LSP
      responses:
        '200':
          description: LSP servers list

  /v1/lsp/execute:
    post:
      summary: Execute LSP request
      description: Executes a Language Server Protocol request
      operationId: executeLSPRequest
      tags:
        - LSP
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                method:
                  type: string
                params:
                  type: object
      responses:
        '200':
          description: LSP response

  /v1/lsp/sync:
    post:
      summary: Sync LSP servers
      description: Synchronizes LSP server configurations
      operationId: syncLSPServers
      tags:
        - LSP
      responses:
        '200':
          description: Sync completed

  /v1/lsp/stats:
    get:
      summary: Get LSP statistics
      description: Returns statistics about LSP operations
      operationId: getLSPStats
      tags:
        - LSP
      responses:
        '200':
          description: LSP statistics

  /v1/mcp/capabilities:
    get:
      summary: Get MCP capabilities
      description: Returns Model Context Protocol capabilities
      operationId: getMCPCapabilities
      tags:
        - MCP
      responses:
        '200':
          description: MCP capabilities

  /v1/mcp/tools:
    get:
      summary: List MCP tools
      description: Returns available MCP tools
      operationId: listMCPTools
      tags:
        - MCP
      responses:
        '200':
          description: MCP tools list

  /v1/mcp/tools/call:
    post:
      summary: Call MCP tool
      description: Executes an MCP tool
      operationId: callMCPTool
      tags:
        - MCP
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                arguments:
                  type: object
      responses:
        '200':
          description: Tool execution result

  /v1/mcp/prompts:
    get:
      summary: List MCP prompts
      description: Returns available MCP prompts
      operationId: listMCPPrompts
      tags:
        - MCP
      responses:
        '200':
          description: MCP prompts list

  /v1/mcp/resources:
    get:
      summary: List MCP resources
      description: Returns available MCP resources
      operationId: listMCPResources
      tags:
        - MCP
      responses:
        '200':
          description: MCP resources list

  /v1/protocols/execute:
    post:
      summary: Execute protocol request
      description: Executes a protocol-agnostic request
      operationId: executeProtocolRequest
      tags:
        - Protocols
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Protocol response

  /v1/protocols/servers:
    get:
      summary: List protocol servers
      description: Returns all configured protocol servers
      operationId: listProtocolServers
      tags:
        - Protocols
      responses:
        '200':
          description: Protocol servers list

  /v1/protocols/metrics:
    get:
      summary: Get protocol metrics
      description: Returns metrics for protocol operations
      operationId: getProtocolMetrics
      tags:
        - Protocols
      responses:
        '200':
          description: Protocol metrics

  /v1/protocols/refresh:
    post:
      summary: Refresh protocol servers
      description: Refreshes protocol server connections
      operationId: refreshProtocolServers
      tags:
        - Protocols
      responses:
        '200':
          description: Refresh completed

  /v1/protocols/configure:
    post:
      summary: Configure protocols
      description: Updates protocol configurations
      operationId: configureProtocols
      tags:
        - Protocols
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Configuration updated

  /v1/embeddings/generate:
    post:
      summary: Generate embeddings
      description: Generates vector embeddings for text
      operationId: generateEmbeddings
      tags:
        - Embeddings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: array
                  items:
                    type: string
                model:
                  type: string
      responses:
        '200':
          description: Embeddings generated

  /v1/embeddings/search:
    post:
      summary: Vector search
      description: Performs similarity search using embeddings
      operationId: vectorSearch
      tags:
        - Embeddings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                limit:
                  type: integer
      responses:
        '200':
          description: Search results

  /v1/embeddings/index:
    post:
      summary: Index document
      description: Indexes a document for vector search
      operationId: indexDocument
      tags:
        - Embeddings
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Document indexed

  /v1/embeddings/batch-index:
    post:
      summary: Batch index documents
      description: Indexes multiple documents at once
      operationId: batchIndexDocuments
      tags:
        - Embeddings
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Documents indexed

  /v1/embeddings/stats:
    get:
      summary: Get embedding statistics
      description: Returns statistics about embeddings
      operationId: getEmbeddingStats
      tags:
        - Embeddings
      responses:
        '200':
          description: Embedding statistics

  /v1/embeddings/providers:
    get:
      summary: List embedding providers
      description: Returns available embedding providers
      operationId: listEmbeddingProviders
      tags:
        - Embeddings
      responses:
        '200':
          description: Embedding providers list

  /v1/cognee/health:
    get:
      summary: Cognee health check
      description: Returns health status of Cognee service
      operationId: cogneeHealth
      tags:
        - Cognee
      responses:
        '200':
          description: Cognee is healthy

  /v1/cognee/stats:
    get:
      summary: Get Cognee statistics
      description: Returns Cognee usage statistics
      operationId: getCogneeStats
      tags:
        - Cognee
      responses:
        '200':
          description: Cognee statistics

  /v1/cognee/config:
    get:
      summary: Get Cognee configuration
      description: Returns current Cognee configuration
      operationId: getCogneeConfig
      tags:
        - Cognee
      responses:
        '200':
          description: Cognee configuration

  /v1/cognee/start:
    post:
      summary: Start Cognee service
      description: Ensures Cognee service is running
      operationId: startCognee
      tags:
        - Cognee
      responses:
        '200':
          description: Cognee started

  /v1/cognee/memory:
    post:
      summary: Add memory to Cognee
      description: Adds content to Cognee memory
      operationId: addCogneeMemory
      tags:
        - Cognee
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                metadata:
                  type: object
      responses:
        '200':
          description: Memory added

  /v1/cognee/search:
    post:
      summary: Search Cognee memory
      description: Searches Cognee knowledge graph
      operationId: searchCogneeMemory
      tags:
        - Cognee
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
      responses:
        '200':
          description: Search results

  /v1/cognee/cognify:
    post:
      summary: Cognify content
      description: Processes content through Cognee's cognification pipeline
      operationId: cognifyContent
      tags:
        - Cognee
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Content cognified

  /v1/cognee/insights:
    post:
      summary: Get insights
      description: Generates insights from Cognee knowledge
      operationId: getCogneeInsights
      tags:
        - Cognee
      responses:
        '200':
          description: Insights generated

  /v1/cognee/graph/complete:
    post:
      summary: Complete graph query
      description: Performs graph completion query
      operationId: graphComplete
      tags:
        - Cognee
      responses:
        '200':
          description: Graph completion result

  /v1/cognee/code:
    post:
      summary: Process code
      description: Processes code through Cognee
      operationId: processCode
      tags:
        - Cognee
      responses:
        '200':
          description: Code processed

  /v1/cognee/feedback:
    post:
      summary: Provide feedback
      description: Provides feedback to improve Cognee
      operationId: provideFeedback
      tags:
        - Cognee
      responses:
        '200':
          description: Feedback received

  # CLI Agent Registry endpoints
  /v1/agents:
    get:
      summary: List all CLI agents
      description: Returns list of all 18 supported CLI agents with their capabilities
      operationId: listAgents
      tags:
        - Agents
      responses:
        '200':
          description: List of agents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentListResponse'

  /v1/agents/{name}:
    get:
      summary: Get agent details
      description: Returns detailed information about a specific CLI agent
      operationId: getAgent
      tags:
        - Agents
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: Agent name (e.g., OpenCode, ClaudeCode, KiloCode)
      responses:
        '200':
          description: Agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '404':
          description: Agent not found

  /v1/agents/protocol/{protocol}:
    get:
      summary: List agents by protocol
      description: Returns agents that support a specific protocol
      operationId: listAgentsByProtocol
      tags:
        - Agents
      parameters:
        - name: protocol
          in: path
          required: true
          schema:
            type: string
            enum: [OpenAI, Anthropic, MCP, AWS, Ollama]
      responses:
        '200':
          description: List of agents supporting the protocol
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentListResponse'

  /v1/agents/tool/{tool}:
    get:
      summary: List agents by tool
      description: Returns agents that support a specific tool
      operationId: listAgentsByTool
      tags:
        - Agents
      parameters:
        - name: tool
          in: path
          required: true
          schema:
            type: string
            enum: [Bash, Read, Write, Edit, Glob, Grep, Git, Diff, Test, Lint, TreeView, FileInfo, Symbols, References, Definition, PR, Issue, Workflow, WebFetch, WebSearch, Task]
      responses:
        '200':
          description: List of agents supporting the tool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentListResponse'

  # Provider verification and discovery endpoints
  /v1/providers/verification:
    get:
      summary: Get all providers verification status
      description: Returns verification status for all registered providers
      operationId: getAllProvidersVerification
      tags:
        - Providers
      responses:
        '200':
          description: Verification status for all providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderVerificationResponse'

  /v1/providers/verify:
    post:
      summary: Verify all providers
      description: Triggers verification of all registered providers
      operationId: verifyAllProviders
      tags:
        - Providers
      responses:
        '200':
          description: Verification initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderVerificationResponse'

  /v1/providers/discovery:
    get:
      summary: Get provider discovery summary
      description: Returns summary of auto-discovered providers from environment
      operationId: getDiscoverySummary
      tags:
        - Providers
      responses:
        '200':
          description: Discovery summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderDiscoveryResponse'

  /v1/providers/discover:
    post:
      summary: Discover and verify providers
      description: Auto-discovers providers from environment and verifies them
      operationId: discoverAndVerifyProviders
      tags:
        - Providers
      responses:
        '200':
          description: Discovery and verification completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderDiscoveryResponse'

  /v1/providers/rediscover:
    post:
      summary: Re-discover providers
      description: Re-runs provider discovery from environment
      operationId: reDiscoverProviders
      tags:
        - Providers
      responses:
        '200':
          description: Re-discovery completed

  /v1/providers/best:
    get:
      summary: Get best providers
      description: Returns the highest-scoring providers based on LLMsVerifier scores
      operationId: getBestProviders
      tags:
        - Providers
      responses:
        '200':
          description: Best providers ranked by score
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BestProvidersResponse'

  /v1/providers/{id}/verification:
    get:
      summary: Get provider verification status
      description: Returns verification status for a specific provider
      operationId: getProviderVerification
      tags:
        - Providers
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Provider verification status

  /v1/providers/{id}/verify:
    post:
      summary: Verify specific provider
      description: Triggers verification for a specific provider
      operationId: verifyProvider
      tags:
        - Providers
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Provider verification completed

  # Debate team configuration
  /v1/debates/team:
    get:
      summary: Get debate team configuration
      description: Returns the current AI debate team configuration with all 15 LLMs
      operationId: getDebateTeam
      tags:
        - Debates
      responses:
        '200':
          description: Debate team configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebateTeamResponse'

  # Protocol SSE endpoints for CLI agents
  /v1/mcp:
    get:
      summary: MCP SSE endpoint
      description: Server-Sent Events endpoint for MCP protocol (CLI agents)
      operationId: mcpSSE
      tags:
        - Protocols
      responses:
        '200':
          description: SSE event stream
          content:
            text/event-stream:
              schema:
                type: string

  /v1/acp:
    get:
      summary: ACP SSE endpoint
      description: Server-Sent Events endpoint for ACP protocol (CLI agents)
      operationId: acpSSE
      tags:
        - Protocols
      responses:
        '200':
          description: SSE event stream
          content:
            text/event-stream:
              schema:
                type: string

  /v1/vision:
    get:
      summary: Vision SSE endpoint
      description: Server-Sent Events endpoint for Vision protocol (CLI agents)
      operationId: visionSSE
      tags:
        - Protocols
      responses:
        '200':
          description: SSE event stream
          content:
            text/event-stream:
              schema:
                type: string

  /v1/providers/{id}:
    get:
      summary: Get provider details
      description: Returns details of a specific provider
      operationId: getProvider
      tags:
        - Providers
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Provider details
    put:
      summary: Update provider
      description: Updates provider configuration
      operationId: updateProvider
      tags:
        - Providers
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Provider updated
    delete:
      summary: Delete provider
      description: Removes a provider
      operationId: deleteProvider
      tags:
        - Providers
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Provider deleted

  /v1/completion:
    post:
      summary: Single completion
      description: Run a skills-enhanced completion with intent-based routing
      operationId: complete
      tags:
        - Completion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: Completion result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompletionResponse'

  /v1/completion/stream:
    post:
      summary: Streaming completion
      operationId: completeStream
      tags:
        - Completion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: SSE stream

  /v1/completion/chat:
    post:
      summary: Chat-style completion
      operationId: chatComplete
      tags:
        - Completion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Chat completion result

  /v1/completion/chat/stream:
    post:
      summary: Streaming chat completion
      operationId: chatCompleteStream
      tags:
        - Completion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: SSE stream

  /v1/completion/models:
    get:
      summary: List completion models
      operationId: listCompletionModels
      tags:
        - Completion
      responses:
        '200':
          description: Available models

  /v1/agentic/workflows:
    post:
      summary: Create and execute workflow
      description: Graph-based agentic workflow orchestration
      operationId: createWorkflow
      tags:
        - Agentic
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - nodes
                - entry_point
              properties:
                name:
                  type: string
                description:
                  type: string
                nodes:
                  type: array
                  items:
                    type: object
                edges:
                  type: array
                  items:
                    type: object
                entry_point:
                  type: string
                end_nodes:
                  type: array
                  items:
                    type: string
                config:
                  type: object
                input:
                  type: object
      responses:
        '200':
          description: Workflow result
        '400':
          description: Invalid request

  /v1/agentic/workflows/{id}:
    get:
      summary: Get workflow status
      operationId: getWorkflow
      tags:
        - Agentic
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Workflow status

  /v1/planning/hiplan:
    post:
      summary: Hierarchical planning
      description: Execute hierarchical planning for a given goal
      operationId: createHiPlan
      tags:
        - Planning
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - goal
              properties:
                goal:
                  type: string
                config:
                  type: object
      responses:
        '200':
          description: Plan result

  /v1/planning/mcts:
    post:
      summary: Monte Carlo Tree Search
      description: Run MCTS planning for decision optimization
      operationId: runMCTS
      tags:
        - Planning
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - goal
              properties:
                goal:
                  type: string
                config:
                  type: object
      responses:
        '200':
          description: MCTS result

  /v1/planning/tot:
    post:
      summary: Tree of Thoughts
      description: Run Tree of Thoughts reasoning
      operationId: runToT
      tags:
        - Planning
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - goal
              properties:
                goal:
                  type: string
                config:
                  type: object
      responses:
        '200':
          description: ToT result

  /v1/llmops/experiments:
    post:
      summary: Create A/B experiment
      operationId: createExperiment
      tags:
        - LLMOps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - variants
              properties:
                name:
                  type: string
                description:
                  type: string
                variants:
                  type: array
                  items:
                    type: object
                traffic_split:
                  type: object
                metrics:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Experiment created
    get:
      summary: List experiments
      operationId: listExperiments
      tags:
        - LLMOps
      responses:
        '200':
          description: List of experiments

  /v1/llmops/experiments/{id}:
    get:
      summary: Get experiment details
      operationId: getExperiment
      tags:
        - LLMOps
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Experiment details

  /v1/llmops/evaluate:
    post:
      summary: Run continuous evaluation
      operationId: createEvaluation
      tags:
        - LLMOps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - dataset
              properties:
                name:
                  type: string
                dataset:
                  type: string
                metrics:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Evaluation started

  /v1/llmops/prompts:
    get:
      summary: List prompt versions
      operationId: listPrompts
      tags:
        - LLMOps
      responses:
        '200':
          description: Prompt versions
    post:
      summary: Create prompt version
      operationId: createPromptVersion
      tags:
        - LLMOps
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Prompt version created

  /v1/benchmark/run:
    post:
      summary: Start benchmark suite
      description: Run SWE-bench, HumanEval, MMLU, or custom benchmarks
      operationId: startBenchmark
      tags:
        - Benchmark
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - benchmark_type
              properties:
                name:
                  type: string
                benchmark_type:
                  type: string
                  enum: [swe_bench, humaneval, mmlu, custom]
                provider_name:
                  type: string
                model_name:
                  type: string
                config:
                  type: object
      responses:
        '201':
          description: Benchmark started

  /v1/benchmark/results:
    get:
      summary: List benchmark results
      operationId: listBenchmarkResults
      tags:
        - Benchmark
      responses:
        '200':
          description: Benchmark results

  /v1/benchmark/results/{id}:
    get:
      summary: Get specific benchmark result
      operationId: getBenchmarkResult
      tags:
        - Benchmark
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Benchmark result details

  /v1/discovery/models:
    get:
      summary: Get discovered models
      description: Returns all models discovered via 3-tier discovery
      operationId: getDiscoveredModels
      tags:
        - Discovery
      responses:
        '200':
          description: Discovered models

  /v1/discovery/models/selected:
    get:
      summary: Get selected models
      operationId: getSelectedModels
      tags:
        - Discovery
      responses:
        '200':
          description: Selected models

  /v1/discovery/stats:
    get:
      summary: Get discovery statistics
      operationId: getDiscoveryStats
      tags:
        - Discovery
      responses:
        '200':
          description: Discovery statistics

  /v1/discovery/trigger:
    post:
      summary: Trigger model discovery
      operationId: triggerDiscovery
      tags:
        - Discovery
      responses:
        '200':
          description: Discovery triggered

  /v1/discovery/ensemble:
    get:
      summary: Get ensemble models
      operationId: getEnsembleModels
      tags:
        - Discovery
      responses:
        '200':
          description: Ensemble models

  /v1/discovery/debate-model:
    get:
      summary: Get best debate model
      operationId: getModelForDebate
      tags:
        - Discovery
      responses:
        '200':
          description: Best debate model

  /v1/scoring/model/{model_id}:
    get:
      summary: Get model score
      description: Returns the 5-component weighted score for a model
      operationId: getModelScore
      tags:
        - Scoring
      parameters:
        - name: model_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Model score

  /v1/scoring/top:
    get:
      summary: Get top-scored models
      operationId: getTopModels
      tags:
        - Scoring
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Top models

  /v1/scoring/weights:
    get:
      summary: Get scoring weights
      operationId: getScoringWeights
      tags:
        - Scoring
      responses:
        '200':
          description: Current scoring weights
    put:
      summary: Update scoring weights
      operationId: updateScoringWeights
      tags:
        - Scoring
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Weights updated

  /v1/verification/model:
    post:
      summary: Verify a model
      description: Run 8-test verification pipeline on a model
      operationId: verifyModel
      tags:
        - Verification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model_id
              properties:
                model_id:
                  type: string
                provider:
                  type: string
      responses:
        '200':
          description: Verification result

  /v1/verification/status:
    get:
      summary: Get verification status
      operationId: getVerificationStatus
      tags:
        - Verification
      responses:
        '200':
          description: Verification status

  /v1/verification/models:
    get:
      summary: Get verified models
      operationId: getVerifiedModels
      tags:
        - Verification
      responses:
        '200':
          description: List of verified models

  /v1/rag/health:
    get:
      summary: RAG system health
      operationId: ragHealth
      tags:
        - RAG
      responses:
        '200':
          description: RAG health status

  /v1/rag/documents:
    post:
      summary: Ingest document
      operationId: ingestDocument
      tags:
        - RAG
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                metadata:
                  type: object
                chunk_strategy:
                  type: string
      responses:
        '200':
          description: Document ingested

  /v1/rag/search:
    post:
      summary: Search documents
      operationId: ragSearch
      tags:
        - RAG
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                limit:
                  type: integer
                threshold:
                  type: number
                filters:
                  type: object
      responses:
        '200':
          description: Search results

  /v1/rag/search/hybrid:
    post:
      summary: Hybrid search
      operationId: ragHybridSearch
      tags:
        - RAG
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                dense_weight:
                  type: number
                sparse_weight:
                  type: number
                limit:
                  type: integer
      responses:
        '200':
          description: Hybrid search results

  /v1/search/semantic:
    post:
      summary: Semantic code search
      operationId: semanticSearch
      tags:
        - Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                language:
                  type: string
                file_pattern:
                  type: string
                top_k:
                  type: integer
                min_score:
                  type: number
      responses:
        '200':
          description: Search results

  /v1/search/index:
    post:
      summary: Trigger code indexing
      operationId: triggerIndex
      tags:
        - Search
      responses:
        '200':
          description: Indexing result

  /v1/templates:
    get:
      summary: List templates
      operationId: listTemplates
      tags:
        - Templates
      responses:
        '200':
          description: Template list

  /v1/templates/{id}:
    get:
      summary: Get template
      operationId: getTemplate
      tags:
        - Templates
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Template details

  /v1/templates/apply:
    post:
      summary: Apply template
      operationId: applyTemplate
      tags:
        - Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - template_id
              properties:
                template_id:
                  type: string
                variables:
                  type: object
      responses:
        '200':
          description: Template applied

  /v1/checkpoints:
    get:
      summary: List checkpoints
      operationId: listCheckpoints
      tags:
        - Checkpoints
      responses:
        '200':
          description: Checkpoint list
    post:
      summary: Create checkpoint
      operationId: createCheckpoint
      tags:
        - Checkpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                description:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Checkpoint created

  /v1/checkpoints/{id}/restore:
    post:
      summary: Restore checkpoint
      operationId: restoreCheckpoint
      tags:
        - Checkpoints
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Checkpoint restored

  /v1/browser/navigate:
    post:
      summary: Navigate to URL
      operationId: browserNavigate
      tags:
        - Browser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                wait_for:
                  type: string
                timeout:
                  type: integer
      responses:
        '200':
          description: Navigation result

  /v1/browser/screenshot:
    post:
      summary: Take screenshot
      operationId: browserScreenshot
      tags:
        - Browser
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                selector:
                  type: string
                full_page:
                  type: boolean
      responses:
        '200':
          description: Screenshot data

  /v1/skills:
    get:
      summary: List skills
      operationId: listSkills
      tags:
        - Skills
      responses:
        '200':
          description: Skill list

  /v1/skills/categories:
    get:
      summary: List skill categories
      operationId: listSkillCategories
      tags:
        - Skills
      responses:
        '200':
          description: Categories

  /v1/skills/match:
    post:
      summary: Match skills to query
      operationId: matchSkills
      tags:
        - Skills
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                limit:
                  type: integer
      responses:
        '200':
          description: Matched skills

  /v1/qa/sessions:
    post:
      summary: Start QA session
      description: Start an autonomous QA session across platforms
      operationId: startQASession
      tags:
        - QA
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - project_root
              properties:
                project_root:
                  type: string
                platforms:
                  type: array
                  items:
                    type: string
                web_url:
                  type: string
                output_dir:
                  type: string
      responses:
        '200':
          description: QA session result

  /v1/qa/findings:
    get:
      summary: List QA findings
      operationId: listFindings
      tags:
        - QA
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [open, fixed, verified]
      responses:
        '200':
          description: List of findings

  /v1/qa/platforms:
    get:
      summary: List QA platforms
      operationId: listPlatforms
      tags:
        - QA
      responses:
        '200':
          description: Supported platforms

  /v1/features:
    get:
      summary: Get enabled features
      operationId: getFeatures
      tags:
        - Features
      security: []
      responses:
        '200':
          description: Feature flags

  /v1/features/available:
    get:
      summary: Get all available features
      operationId: getAvailableFeatures
      tags:
        - Features
      security: []
      responses:
        '200':
          description: All features

  /v1/features/agents:
    get:
      summary: Get agent capabilities
      operationId: getAgentCapabilities
      tags:
        - Features
      security: []
      responses:
        '200':
          description: Agent feature matrix

  /v1/graphql:
    post:
      summary: GraphQL endpoint
      description: Feature-flagged GraphQL endpoint (requires GRAPHQL_ENABLED=true)
      operationId: graphql
      tags:
        - GraphQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                variables:
                  type: object
      responses:
        '200':
          description: GraphQL response

  /v1/monitoring/concurrency:
    get:
      summary: Get concurrency status
      operationId: getConcurrencyStatus
      tags:
        - Monitoring
      responses:
        '200':
          description: Concurrency monitoring data

  /v1/monitoring/concurrency/alerts:
    get:
      summary: Get concurrency alerts
      operationId: getConcurrencyAlerts
      tags:
        - Monitoring
      responses:
        '200':
          description: Alert statistics

  /v1/startup/verification:
    get:
      summary: Get startup verification results
      operationId: getStartupVerification
      tags:
        - Monitoring
      security: []
      responses:
        '200':
          description: Startup verification status

  /v1/tasks:
    post:
      summary: Create background task
      operationId: createTask
      tags:
        - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                command:
                  type: string
                working_dir:
                  type: string
                priority:
                  type: string
      responses:
        '201':
          description: Task created
    get:
      summary: List tasks
      operationId: listTasks
      tags:
        - Tasks
      responses:
        '200':
          description: Task list

  /v1/tasks/{id}:
    get:
      summary: Get task details
      operationId: getTask
      tags:
        - Tasks
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Task details
    delete:
      summary: Delete task
      operationId: deleteTask
      tags:
        - Tasks
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Task deleted

  /v1/tasks/{id}/cancel:
    post:
      summary: Cancel task
      operationId: cancelTask
      tags:
        - Tasks
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Task cancelled

  /v1/webhooks:
    post:
      summary: Register webhook
      operationId: registerWebhook
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                events:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Webhook registered
    get:
      summary: List webhooks
      operationId: listWebhooks
      tags:
        - Webhooks
      responses:
        '200':
          description: Webhook list

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT authentication token

  schemas:
    EnhancedHealthResponse:
      type: object
      properties:
        status:
          type: string
          example: healthy
        providers:
          type: object
          properties:
            total:
              type: integer
            healthy:
              type: integer
            unhealthy:
              type: integer
        timestamp:
          type: integer

    RegisterRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
        name:
          type: string

    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string

    RefreshRequest:
      type: object
      required:
        - refreshToken
      properties:
        refreshToken:
          type: string

    AuthResponse:
      type: object
      properties:
        token:
          type: string
        refreshToken:
          type: string
        expiresAt:
          type: string
          format: date-time
        user:
          $ref: '#/components/schemas/UserInfo'

    UserInfo:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        role:
          type: string
          enum: [user, admin]
        createdAt:
          type: string
          format: date-time

    ModelsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'

    Model:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: model
        provider:
          type: string
        created:
          type: integer
        owned_by:
          type: string

    ProvidersResponse:
      type: object
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/Provider'
        count:
          type: integer

    Provider:
      type: object
      properties:
        name:
          type: string
        supported_models:
          type: array
          items:
            type: string
        supported_features:
          type: array
          items:
            type: string
        supports_streaming:
          type: boolean
        supports_function_calling:
          type: boolean
        supports_vision:
          type: boolean
        metadata:
          type: object
          additionalProperties: true

    ProviderHealthResponse:
      type: object
      properties:
        provider:
          type: string
        healthy:
          type: boolean
        error:
          type: string
        circuit_breaker:
          type: object
          properties:
            state:
              type: string
              enum: [closed, open, half_open]
            failure_count:
              type: integer
            last_failure:
              type: string
              format: date-time

    CompletionRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: The prompt to complete
        model:
          type: string
          description: Model to use
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 0.7
        max_tokens:
          type: integer
          minimum: 1
          maximum: 4096
          default: 1000
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 1.0
        stop:
          type: array
          items:
            type: string
        memory_enhanced:
          type: boolean
          default: false

    CompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              text:
                type: string
              finish_reason:
                type: string
        usage:
          $ref: '#/components/schemas/Usage'

    ChatCompletionRequest:
      type: object
      required:
        - messages
      properties:
        model:
          type: string
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 0.7
        max_tokens:
          type: integer
          minimum: 1
          maximum: 4096
        top_p:
          type: number
          minimum: 0
          maximum: 1
        stream:
          type: boolean
          default: false

    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [system, user, assistant, function, tool]
        content:
          type: string
        name:
          type: string
        tool_calls:
          type: array
          items:
            type: object

    ChatCompletionResponse:
      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:
          $ref: '#/components/schemas/Usage'

    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer

    EnsembleCompletionRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        model:
          type: string
        temperature:
          type: number
        max_tokens:
          type: integer
        ensemble_config:
          $ref: '#/components/schemas/EnsembleConfig'
        memory_enhanced:
          type: boolean

    EnsembleConfig:
      type: object
      properties:
        strategy:
          type: string
          enum: [confidence_weighted, majority_vote, best_of_n, consensus]
          default: confidence_weighted
        min_providers:
          type: integer
          minimum: 1
          default: 2
        confidence_threshold:
          type: number
          minimum: 0
          maximum: 1
          default: 0.8
        fallback_to_best:
          type: boolean
          default: true
        timeout:
          type: integer
          description: Timeout in seconds
          default: 30
        preferred_providers:
          type: array
          items:
            type: string

    EnsembleCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: ensemble.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:
          $ref: '#/components/schemas/Usage'
        ensemble:
          type: object
          properties:
            voting_method:
              type: string
            responses_count:
              type: integer
            scores:
              type: object
              additionalProperties:
                type: number
            metadata:
              type: object
            selected_provider:
              type: string
            selection_score:
              type: number

    GraphVisualization:
      type: object
      properties:
        nodes:
          type: array
          items:
            type: object
        edges:
          type: array
          items:
            type: object
        layout:
          type: object

    DatasetsResponse:
      type: object
      properties:
        datasets:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              created_at:
                type: string
                format: date-time

    ModelMetadataListResponse:
      type: object
      properties:
        models:
          type: array
          items:
            $ref: '#/components/schemas/ModelMetadata'
        count:
          type: integer

    ModelMetadata:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        provider:
          type: string
        capabilities:
          type: array
          items:
            type: string
        context_length:
          type: integer
        pricing:
          type: object
          properties:
            input:
              type: number
            output:
              type: number
        last_updated:
          type: string
          format: date-time

    ModelBenchmarks:
      type: object
      properties:
        model_id:
          type: string
        benchmarks:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              score:
                type: number
              date:
                type: string
                format: date-time

    ModelComparison:
      type: object
      properties:
        models:
          type: array
          items:
            $ref: '#/components/schemas/ModelMetadata'
        comparison:
          type: object
          additionalProperties: true

    AllProviderHealthResponse:
      type: object
      properties:
        provider_health:
          type: object
          additionalProperties:
            type: string
        timestamp:
          type: integer

    RefreshStatus:
      type: object
      properties:
        status:
          type: string
          enum: [pending, running, completed, failed]
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        models_updated:
          type: integer
        errors:
          type: array
          items:
            type: string

    DebateRequest:
      type: object
      required:
        - debateId
        - topic
        - participants
        - maxRounds
        - timeout
      properties:
        debateId:
          type: string
          description: Unique identifier for the debate
          example: "debate-123"
        topic:
          type: string
          description: The debate topic or question
          example: "Should AI be regulated?"
        participants:
          type: array
          minItems: 2
          maxItems: 10
          items:
            $ref: '#/components/schemas/Participant'
        maxRounds:
          type: integer
          description: Maximum number of debate rounds
          minimum: 1
          maximum: 10
          example: 3
        timeout:
          type: integer
          description: Total timeout in seconds
          minimum: 60
          maximum: 3600
          example: 300
        strategy:
          type: string
          description: Debate strategy to use
          enum: [structured, free_form, round_robin, socratic, adversarial]
          default: "structured"
        enableCognee:
          type: boolean
          description: Enable Cognee AI enhancement
          default: false
        metadata:
          type: object
          description: Additional metadata
          additionalProperties: true

    Participant:
      type: object
      required:
        - participantId
        - name
        - role
        - llmProvider
        - llmModel
      properties:
        participantId:
          type: string
          description: Unique identifier for the participant
          example: "participant-1"
        name:
          type: string
          description: Participant name
          example: "Alice"
        role:
          type: string
          description: Participant role in the debate
          enum: [proponent, opponent, neutral, moderator]
          example: "proponent"
        llmProvider:
          type: string
          description: LLM provider to use
          enum: [claude, deepseek, gemini, qwen, zai, ollama, openrouter]
          example: "claude"
        llmModel:
          type: string
          description: Specific model to use
          example: "claude-3-opus-20240229"
        maxRounds:
          type: integer
          description: Maximum rounds for this participant
          minimum: 1
          maximum: 10
          example: 3
        timeout:
          type: integer
          description: Timeout for this participant in seconds
          minimum: 30
          maximum: 600
          example: 120
        weight:
          type: number
          description: Voting weight for this participant
          minimum: 0.1
          maximum: 5.0
          example: 1.0

    DebateResponse:
      type: object
      properties:
        debateId:
          type: string
          description: Unique identifier for the created debate
        status:
          type: string
          description: Current status of the debate
          enum: [created, running, completed, failed]
        startTime:
          type: string
          format: date-time
          description: When the debate was started
        estimatedEndTime:
          type: string
          format: date-time
          description: Estimated completion time
        message:
          type: string
          description: Status message

    DebateDetails:
      type: object
      properties:
        debateId:
          type: string
        topic:
          type: string
        status:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        duration:
          type: integer
          description: Duration in seconds
        totalRounds:
          type: integer
        currentRound:
          type: integer
        participants:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantDetails'
        consensus:
          $ref: '#/components/schemas/ConsensusResult'
        qualityScore:
          type: number
          minimum: 0
          maximum: 1
        success:
          type: boolean
        errorMessage:
          type: string

    ParticipantDetails:
      type: object
      properties:
        participantId:
          type: string
        name:
          type: string
        role:
          type: string
        status:
          type: string
        currentResponse:
          type: string
        responseTime:
          type: integer
        error:
          type: string

    ConsensusResult:
      type: object
      properties:
        achieved:
          type: boolean
        confidence:
          type: number
        agreementLevel:
          type: number
        finalPosition:
          type: string
        keyPoints:
          type: array
          items:
            type: string
        disagreements:
          type: array
          items:
            type: string
        timestamp:
          type: string
          format: date-time

    # CLI Agent schemas
    Agent:
      type: object
      properties:
        name:
          type: string
          description: Agent name
          example: OpenCode
        language:
          type: string
          description: Implementation language
          example: Go
        configFormat:
          type: string
          description: Configuration format
          enum: [JSON, YAML, TOML, ENV, Proto]
        apiPattern:
          type: string
          description: API pattern used
          enum: [OpenAI, Anthropic, Multi, DeepSeek, Google, AWS, Ollama, Mistral, Qwen]
        protocols:
          type: array
          items:
            type: string
          description: Supported protocols
        tools:
          type: array
          items:
            type: string
          description: Supported tools (21 total)
        features:
          type: array
          items:
            type: string
          description: Key features
        description:
          type: string
          description: Agent description

    AgentListResponse:
      type: object
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
        count:
          type: integer
          description: Total number of agents

    # Provider verification and discovery schemas
    ProviderVerificationResponse:
      type: object
      properties:
        providers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              verified:
                type: boolean
              score:
                type: number
              status:
                type: string
                enum: [healthy, unhealthy, auth_failed, timeout]
              lastVerified:
                type: string
                format: date-time
        totalProviders:
          type: integer
        verifiedCount:
          type: integer
        timestamp:
          type: string
          format: date-time

    ProviderDiscoveryResponse:
      type: object
      properties:
        discovered:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
              envVar:
                type: string
              verified:
                type: boolean
              score:
                type: number
        totalDiscovered:
          type: integer
        oauthProviders:
          type: integer
        apiKeyProviders:
          type: integer

    BestProvidersResponse:
      type: object
      properties:
        providers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              score:
                type: number
              rank:
                type: integer
              isOAuth:
                type: boolean
              models:
                type: array
                items:
                  type: string

    DebateTeamResponse:
      type: object
      properties:
        positions:
          type: array
          items:
            type: object
            properties:
              position:
                type: integer
              role:
                type: string
              primary:
                type: object
                properties:
                  provider:
                    type: string
                  model:
                    type: string
                  score:
                    type: number
              fallbacks:
                type: array
                items:
                  type: object
                  properties:
                    provider:
                      type: string
                    model:
                      type: string
                    score:
                      type: number
        totalLLMs:
          type: integer
          description: Total LLMs in team (15)
        oauthCount:
          type: integer
          description: OAuth providers count
        verifierCount:
          type: integer
          description: LLMsVerifier providers count

    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error details
        timestamp:
          type: string
          format: date-time
          description: When the error occurred

tags:
  - name: Monitoring
    description: Health checks and metrics
  - name: Authentication
    description: User authentication and authorization
  - name: Models
    description: Model listing and metadata
  - name: Providers
    description: LLM provider management
  - name: Completions
    description: Text completion operations
  - name: Chat
    description: Chat completion operations
  - name: Ensemble
    description: Multi-provider ensemble operations
  - name: Cognee
    description: Cognee AI enhancement
  - name: Debates
    description: AI debate operations
  - name: Agents
    description: CLI agent registry and capabilities (18 supported agents with 21 tools)
  - name: Protocols
    description: Protocol SSE endpoints (MCP, ACP, Vision) for CLI agent integration
  - name: Admin
    description: Administrative operations

externalDocs:
  description: Find more information about HelixAgent
  url: https://docs.helixagent.ai