altus4.openapi.yaml

openapi: 3.0.3
info:
  title: Altus4 Core API
  version: 0.4.0
  description: |
    Complete API specification for Altus4 - AI-Enhanced MySQL Full-Text Search Engine.

    ## Authentication

    Altus4 uses dual authentication:
    - **JWT Bearer Tokens**: For user management, API key management, database management, and analytics
    - **API Key Bearer Tokens**: For search operations and B2B service integration

    API Key format: `altus4_sk_{env}_{secret}` where env is 'test' or 'live'.

servers:
  - url: http://localhost:3000
    description: Local development server

tags:
  - name: Auth
    description: User authentication and profile management
  - name: Management
    description: System management and setup operations
  - name: API Keys
    description: API key management for B2B integration
  - name: Database
    description: Database connection management
  - name: Search
    description: Search operations with AI enhancement
  - name: Analytics
    description: Search analytics and insights

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for user authentication
    apiKeyAuth:
      type: http
      scheme: bearer
      description: API key for search operations (format altus4_sk_{env}_{secret})

  schemas:
    ApiResponse:
      type: object
      required: [success]
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        data:
          description: Response data (varies by endpoint)
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code for programmatic handling
            message:
              type: string
              description: Human-readable error message
            details:
              description: Additional error details
        meta:
          type: object
          properties:
            timestamp:
              type: string
              format: date-time
            requestId:
              type: string
            version:
              type: string
            executionTime:
              type: number
              description: Request execution time in milliseconds
            apiKeyTier:
              type: string
              description: Present on API key authenticated responses

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        role:
          type: string
          enum: [user, admin]
        connectedDatabases:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        lastActive:
          type: string
          format: date-time

    ApiKey:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        keyPrefix:
          type: string
          description: Public prefix of the API key
        environment:
          type: string
          enum: [test, live]
        permissions:
          type: array
          items:
            type: string
            enum: [search, analytics, admin]
        rateLimitTier:
          type: string
          enum: [free, pro, enterprise]
        expiresAt:
          type: string
          format: date-time
          nullable: true
        lastUsed:
          type: string
          format: date-time
          nullable: true
        lastUsedIp:
          type: string
          nullable: true
        usageCount:
          type: integer
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    DatabaseConnection:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        host:
          type: string
        port:
          type: integer
        database:
          type: string
        username:
          type: string
        ssl:
          type: boolean
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    SearchRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 500
          description: Search query text
        databases:
          type: array
          items:
            type: string
            format: uuid
          description: Database IDs to search in
        tables:
          type: array
          items:
            type: string
          description: Specific table names to search
        columns:
          type: array
          items:
            type: string
          description: Specific column names to search
        searchMode:
          type: string
          enum: [natural, boolean, semantic]
          default: natural
          description: Search mode to use
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
          description: Maximum number of results
        offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of results to skip
        includeAnalytics:
          type: boolean
          default: false
          description: Include analytics data in response

    SearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              table:
                type: string
              database:
                type: string
              relevanceScore:
                type: number
              matchedColumns:
                type: array
                items:
                  type: string
              data:
                type: object
                additionalProperties: true
              snippet:
                type: string
              categories:
                type: array
                items:
                  type: string
        categories:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              count:
                type: integer
              confidence:
                type: number
        suggestions:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              score:
                type: number
              type:
                type: string
                enum: [spelling, semantic, popular]
        trends:
          type: array
          items:
            type: object
            properties:
              period:
                type: string
                enum: [day, week, month, 3months, 6months, year]
              topQueries:
                type: array
                items:
                  type: string
              queryVolume:
                type: number
              avgResponseTime:
                type: number
              popularCategories:
                type: array
                items:
                  type: string
        queryOptimization:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum: [index, query, schema]
              description:
                type: string
              impact:
                type: string
                enum: [low, medium, high]
              sqlSuggestion:
                type: string
        totalCount:
          type: integer
        executionTime:
          type: number
        page:
          type: integer
        limit:
          type: integer

  responses:
    BadRequest:
      description: Bad Request - Validation error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ApiResponse'
              - type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: VALIDATION_ERROR
                      message:
                        type: string
                        example: Invalid request parameters

    Unauthorized:
      description: Unauthorized - Missing or invalid token
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ApiResponse'
              - type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: INVALID_API_KEY
                      message:
                        type: string
                        example: Missing or invalid API key

    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ApiResponse'
              - type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: INSUFFICIENT_PERMISSIONS
                      message:
                        type: string
                        example: API key lacks required permissions

    NotFound:
      description: Not Found - Resource not found
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ApiResponse'
              - type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: NOT_FOUND
                      message:
                        type: string
                        example: Resource not found

    RateLimitExceeded:
      description: Too Many Requests - Rate limit exceeded
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ApiResponse'
              - type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: RATE_LIMIT_EXCEEDED
                      message:
                        type: string
                        example: Rate limit exceeded. Try again in 45 seconds.

    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ApiResponse'
              - type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: INTERNAL_ERROR
                      message:
                        type: string
                        example: Internal server error

paths:
  # Health Check
  /health:
    get:
      tags: [Management]
      summary: System health check
      description: Check if the system is running and healthy
      responses:
        '200':
          description: System is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
                  timestamp:
                    type: string
                    format: date-time
                  version:
                    type: string
                    example: '0.4.0'
                  uptime:
                    type: number

  # Authentication Endpoints
  /api/v1/auth/register:
    post:
      tags: [Auth]
      summary: Register new user account
      description: Create a new user account with email and password
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password, name]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
                name:
                  type: string
                  minLength: 2
                role:
                  type: string
                  enum: [admin, user]
                  default: user
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          user:
                            $ref: '#/components/schemas/User'
                          token:
                            type: string
                            description: JWT token for authentication
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: User already exists
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: false
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: USER_EXISTS
                          message:
                            type: string
                            example: User with this email already exists

  /api/v1/auth/login:
    post:
      tags: [Auth]
      summary: User login
      description: Authenticate user and receive JWT token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          user:
                            $ref: '#/components/schemas/User'
                          token:
                            type: string
                            description: JWT token for authentication
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: false
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: INVALID_CREDENTIALS
                          message:
                            type: string
                            example: Invalid email or password

  /api/v1/auth/profile:
    get:
      tags: [Auth]
      summary: Get user profile
      description: Get the authenticated user's profile information
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags: [Auth]
      summary: Update user profile
      description: Update the authenticated user's profile information
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 2
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: Profile updated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/auth/change-password:
    post:
      tags: [Auth]
      summary: Change password
      description: Change the authenticated user's password
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [currentPassword, newPassword]
              properties:
                currentPassword:
                  type: string
                newPassword:
                  type: string
                  minLength: 8
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          success:
                            type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/auth/refresh:
    post:
      tags: [Auth]
      summary: Refresh JWT token
      description: Refresh the authentication token
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          user:
                            $ref: '#/components/schemas/User'
                          token:
                            type: string
                            description: New JWT token
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/auth/logout:
    post:
      tags: [Auth]
      summary: User logout
      description: Logout the authenticated user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Logout successful
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          success:
                            type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/auth/account:
    delete:
      tags: [Auth]
      summary: Deactivate account
      description: Deactivate the authenticated user's account
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Account deactivated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          success:
                            type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'

  # Management Endpoints
  /api/v1/management/setup:
    post:
      tags: [Management]
      summary: Create first API key
      description: Create the initial API key for a new user account
      security:
        - bearerAuth: []
      responses:
        '201':
          description: First API key created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          apiKey:
                            $ref: '#/components/schemas/ApiKey'
                          secretKey:
                            type: string
                            description: Full API key (only shown once)
                          warning:
                            type: string
                            example: This is the only time the full API key will be shown. Please store it securely.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: API key already exists
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      success:
                        type: boolean
                        example: false
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: API_KEY_EXISTS
                          message:
                            type: string
                            example: API key already exists for this user

  /api/v1/management/health:
    get:
      tags: [Management]
      summary: Management service health
      description: Check the health of the management service
      responses:
        '200':
          description: Management service is healthy
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          status:
                            type: string
                            example: healthy
                          timestamp:
                            type: string
                            format: date-time
                          version:
                            type: string
                          uptime:
                            type: number
                          authenticationMethods:
                            type: array
                            items:
                              type: string

  /api/v1/management/migration-status:
    get:
      tags: [Management]
      summary: Database migration status
      description: Get the current database migration status
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Migration status retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          userId:
                            type: string
                          hasMigrated:
                            type: boolean
                          recommendedAction:
                            type: string
                          documentation:
                            type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  # API Key Management Endpoints
  /api/v1/keys:
    post:
      tags: [API Keys]
      summary: Create new API key
      description: Create a new API key for the authenticated user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, environment]
              properties:
                name:
                  type: string
                  minLength: 3
                  maxLength: 255
                environment:
                  type: string
                  enum: [test, live]
                permissions:
                  type: array
                  items:
                    type: string
                    enum: [search, analytics, admin]
                  default: [search]
                rateLimitTier:
                  type: string
                  enum: [free, pro, enterprise]
                  default: free
                expiresAt:
                  type: string
                  format: date-time
                  nullable: true
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          apiKey:
                            $ref: '#/components/schemas/ApiKey'
                          secretKey:
                            type: string
                            description: Full API key (only shown once)
                          warning:
                            type: string
                            example: This is the only time the full API key will be shown. Please store it securely.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

    get:
      tags: [API Keys]
      summary: List API keys
      description: Get a list of all API keys for the authenticated user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: API keys retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          apiKeys:
                            type: array
                            items:
                              $ref: '#/components/schemas/ApiKey'
                          total:
                            type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/keys/{keyId}:
    parameters:
      - in: path
        name: keyId
        required: true
        schema:
          type: string
          format: uuid
        description: API key ID

    put:
      tags: [API Keys]
      summary: Update API key
      description: Update an existing API key's properties
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 3
                  maxLength: 255
                permissions:
                  type: array
                  items:
                    type: string
                    enum: [search, analytics, admin]
                rateLimitTier:
                  type: string
                  enum: [free, pro, enterprise]
                expiresAt:
                  type: string
                  format: date-time
                  nullable: true
      responses:
        '200':
          description: API key updated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          apiKey:
                            $ref: '#/components/schemas/ApiKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags: [API Keys]
      summary: Revoke API key
      description: Revoke (deactivate) an API key
      security:
        - bearerAuth: []
      responses:
        '200':
          description: API key revoked successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          success:
                            type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/keys/{keyId}/usage:
    parameters:
      - in: path
        name: keyId
        required: true
        schema:
          type: string
          format: uuid
        description: API key ID

    get:
      tags: [API Keys]
      summary: Get API key usage statistics
      description: Get usage statistics for an API key
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: days
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
          description: Number of days to include in statistics
      responses:
        '200':
          description: Usage statistics retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          usage:
                            type: object
                            properties:
                              apiKeyId:
                                type: string
                              requestCount:
                                type: integer
                              lastUsed:
                                type: string
                                format: date-time
                              rateLimitStatus:
                                type: object
                                properties:
                                  tier:
                                    type: string
                                  remaining:
                                    type: integer
                                  resetTime:
                                    type: string
                                    format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/keys/{keyId}/regenerate:
    parameters:
      - in: path
        name: keyId
        required: true
        schema:
          type: string
          format: uuid
        description: API key ID

    post:
      tags: [API Keys]
      summary: Regenerate API key
      description: Generate a new secret for an existing API key
      security:
        - bearerAuth: []
      responses:
        '200':
          description: API key regenerated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          apiKey:
                            $ref: '#/components/schemas/ApiKey'
                          secretKey:
                            type: string
                            description: New full API key (only shown once)
                          warning:
                            type: string
                            example: This is the only time the new API key will be shown. Please store it securely.
                          oldKeyId:
                            type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # Database Management Endpoints
  /api/v1/databases:
    get:
      tags: [Database]
      summary: List database connections
      description: Get all database connections for the authenticated user
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Database connections retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/DatabaseConnection'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags: [Database]
      summary: Add database connection
      description: Add a new database connection for the authenticated user
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, host, database, username]
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                host:
                  type: string
                  minLength: 1
                port:
                  type: integer
                  minimum: 1
                  maximum: 65535
                  default: 3306
                database:
                  type: string
                  minLength: 1
                username:
                  type: string
                  minLength: 1
                password:
                  type: string
                  description: Database password (will be encrypted)
                ssl:
                  type: boolean
                  default: false
      responses:
        '201':
          description: Database connection added successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DatabaseConnection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/databases/status:
    get:
      tags: [Database]
      summary: Get connection statuses
      description: Get connection status for all user databases
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Connection statuses retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        additionalProperties:
                          type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/databases/{connectionId}:
    parameters:
      - in: path
        name: connectionId
        required: true
        schema:
          type: string
          format: uuid
        description: Database connection ID

    get:
      tags: [Database]
      summary: Get database connection
      description: Get details of a specific database connection
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Database connection retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DatabaseConnection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags: [Database]
      summary: Update database connection
      description: Update an existing database connection
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                host:
                  type: string
                  minLength: 1
                port:
                  type: integer
                  minimum: 1
                  maximum: 65535
                database:
                  type: string
                  minLength: 1
                username:
                  type: string
                  minLength: 1
                password:
                  type: string
                  description: Database password (will be encrypted)
                ssl:
                  type: boolean
      responses:
        '200':
          description: Database connection updated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/DatabaseConnection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags: [Database]
      summary: Remove database connection
      description: Remove a database connection
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Database connection removed successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          success:
                            type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/databases/{connectionId}/test:
    parameters:
      - in: path
        name: connectionId
        required: true
        schema:
          type: string
          format: uuid
        description: Database connection ID

    post:
      tags: [Database]
      summary: Test database connection
      description: Test connectivity to a database
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Connection test completed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          connected:
                            type: boolean
                          message:
                            type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/databases/{connectionId}/schema:
    parameters:
      - in: path
        name: connectionId
        required: true
        schema:
          type: string
          format: uuid
        description: Database connection ID

    get:
      tags: [Database]
      summary: Get database schema
      description: Discover and return the schema of a connected database
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Database schema retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            database:
                              type: string
                            table:
                              type: string
                            columns:
                              type: array
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                  type:
                                    type: string
                                  isFullTextIndexed:
                                    type: boolean
                                  isSearchable:
                                    type: boolean
                                  dataPreview:
                                    type: array
                                    items:
                                      type: string
                            fullTextIndexes:
                              type: array
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                  columns:
                                    type: array
                                    items:
                                      type: string
                                  type:
                                    type: string
                                    enum: [FULLTEXT]
                                  cardinality:
                                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # Search Endpoints
  /api/v1/search:
    post:
      tags: [Search]
      summary: Execute search
      description: Execute a search across specified databases with AI enhancements
      security:
        - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search executed successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/SearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'

  /api/v1/search/suggestions:
    get:
      tags: [Search]
      summary: Get search suggestions
      description: Get search suggestions based on partial query input
      security:
        - apiKeyAuth: []
      parameters:
        - in: query
          name: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 100
          description: Partial query for suggestions
        - in: query
          name: databases
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Database IDs to get suggestions from
        - in: query
          name: tables
          schema:
            type: array
            items:
              type: string
          description: Specific tables to get suggestions from
      responses:
        '200':
          description: Suggestions retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          suggestions:
                            type: array
                            items:
                              type: object
                              properties:
                                text:
                                  type: string
                                score:
                                  type: number
                                type:
                                  type: string
                                  enum: [spelling, semantic, popular]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/search/analyze:
    post:
      tags: [Search]
      summary: Analyze query performance
      description: Analyze a query for performance and get optimization suggestions
      security:
        - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query, databases]
              properties:
                query:
                  type: string
                  minLength: 1
                databases:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Query analysis completed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          query:
                            type: string
                          recommendations:
                            type: array
                            items:
                              type: string
                          performance:
                            type: object
                          optimization:
                            type: array
                            items:
                              type: object
                              properties:
                                type:
                                  type: string
                                  enum: [index, query, schema]
                                description:
                                  type: string
                                impact:
                                  type: string
                                  enum: [low, medium, high]
                                sqlSuggestion:
                                  type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/search/trends:
    get:
      tags: [Search]
      summary: Get search trends
      description: Get search trends for the authenticated API key user
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: Search trends retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            period:
                              type: string
                              enum: [day, week, month, 3months, 6months, year]
                            topQueries:
                              type: array
                              items:
                                type: string
                            queryVolume:
                              type: number
                            avgResponseTime:
                              type: number
                            popularCategories:
                              type: array
                              items:
                                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/search/history:
    get:
      tags: [Search]
      summary: Get search history
      description: Get search history for the authenticated API key user
      security:
        - apiKeyAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Maximum number of results
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of results to skip
      responses:
        '200':
          description: Search history retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            query:
                              type: string
                            database:
                              type: string
                            resultCount:
                              type: integer
                            executionTime:
                              type: number
                            timestamp:
                              type: string
                              format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'

  # Analytics Endpoints
  /api/v1/analytics/search-trends:
    get:
      tags: [Analytics]
      summary: Get search trends analytics
      description: Get detailed search trends and analytics data
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: startDate
          schema:
            type: string
            format: date
          description: Start date for the analytics period
        - in: query
          name: endDate
          schema:
            type: string
            format: date
          description: End date for the analytics period
        - in: query
          name: period
          schema:
            type: string
            enum: [day, week, month, 3months, 6months, year]
            default: week
          description: Analytics period grouping
      responses:
        '200':
          description: Search trends analytics retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            period:
                              type: string
                              enum: [day, week, month, 3months, 6months, year]
                            topQueries:
                              type: array
                              items:
                                type: string
                            queryVolume:
                              type: number
                            avgResponseTime:
                              type: number
                            popularCategories:
                              type: array
                              items:
                                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/analytics/performance:
    get:
      tags: [Analytics]
      summary: Get performance metrics
      description: Get detailed performance metrics and analytics
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: startDate
          schema:
            type: string
            format: date
        - in: query
          name: endDate
          schema:
            type: string
            format: date
        - in: query
          name: period
          schema:
            type: string
            enum: [day, week, month, 3months, 6months, year]
            default: week
      responses:
        '200':
          description: Performance metrics retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          timeSeriesData:
                            type: array
                            items:
                              type: object
                              properties:
                                date:
                                  type: string
                                  format: date
                                avg_response_time:
                                  type: number
                                max_response_time:
                                  type: number
                                min_response_time:
                                  type: number
                                total_queries:
                                  type: integer
                                avg_results:
                                  type: number
                          searchModeDistribution:
                            type: array
                            items:
                              type: object
                              properties:
                                search_mode:
                                  type: string
                                count:
                                  type: integer
                                avg_time:
                                  type: number
                          summary:
                            type: object
                            properties:
                              totalQueries:
                                type: integer
                              averageResponseTime:
                                type: number
                              averageResults:
                                type: number
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/analytics/popular-queries:
    get:
      tags: [Analytics]
      summary: Get popular queries
      description: Get the most popular search queries
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: startDate
          schema:
            type: string
            format: date
        - in: query
          name: endDate
          schema:
            type: string
            format: date
        - in: query
          name: period
          schema:
            type: string
            enum: [day, week, month, 3months, 6months, year]
            default: week
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Popular queries retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            query_text:
                              type: string
                            frequency:
                              type: integer
                            avg_time:
                              type: number
                            avg_results:
                              type: number
                            last_used:
                              type: string
                              format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/analytics/search-history:
    get:
      tags: [Analytics]
      summary: Get detailed search history
      description: Get detailed search history with analytics data
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Search history retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                query:
                                  type: string
                                database:
                                  type: string
                                resultCount:
                                  type: integer
                                executionTime:
                                  type: number
                                timestamp:
                                  type: string
                                  format: date-time
                          total:
                            type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/analytics/insights:
    get:
      tags: [Analytics]
      summary: Get AI-generated insights
      description: Get AI-generated insights about search patterns and performance
      security:
        - bearerAuth: []
      responses:
        '200':
          description: AI insights retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum: [query_optimization, trend_analysis, semantic_enhancement]
                            confidence:
                              type: number
                            description:
                              type: string
                            actionable:
                              type: boolean
                            data:
                              type: object
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/analytics/dashboard:
    get:
      tags: [Analytics]
      summary: Get dashboard data
      description: Get comprehensive dashboard data for analytics overview
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Dashboard data retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          trends:
                            type: object
                          performance:
                            type: object
                          popularQueries:
                            type: array
                            items:
                              type: object
                          insights:
                            type: array
                            items:
                              type: object
                          summary:
                            type: object
        '401':
          $ref: '#/components/responses/Unauthorized'

  # Admin Analytics Endpoints
  /api/v1/analytics/admin/system-overview:
    get:
      tags: [Analytics]
      summary: Get system overview (Admin)
      description: Get system-wide overview data (admin only)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: System overview retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          totalUsers:
                            type: integer
                          totalSearches:
                            type: integer
                          totalDatabases:
                            type: integer
                          systemHealth:
                            type: object
                            properties:
                              status:
                                type: string
                              uptime:
                                type: number
                              memoryUsage:
                                type: number
                              cpuUsage:
                                type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/analytics/admin/user-activity:
    get:
      tags: [Analytics]
      summary: Get user activity (Admin)
      description: Get user activity data across the system (admin only)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User activity data retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          activeUsers:
                            type: integer
                          newUsers:
                            type: integer
                          topUsers:
                            type: array
                            items:
                              type: object
                              properties:
                                userId:
                                  type: string
                                email:
                                  type: string
                                searchCount:
                                  type: integer
                                lastActive:
                                  type: string
                                  format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/analytics/admin/performance-metrics:
    get:
      tags: [Analytics]
      summary: Get system performance metrics (Admin)
      description: Get detailed system performance metrics (admin only)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Performance metrics retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          system:
                            type: object
                            properties:
                              cpuUsage:
                                type: number
                              memoryUsage:
                                type: number
                              diskUsage:
                                type: number
                              uptime:
                                type: number
                          api:
                            type: object
                            properties:
                              requestsPerSecond:
                                type: number
                              averageResponseTime:
                                type: number
                              errorRate:
                                type: number
                          database:
                            type: object
                            properties:
                              connectionPoolUsage:
                                type: number
                              averageQueryTime:
                                type: number
                              slowQueries:
                                type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'