openapi: 3.1.0
info:
  title: Evolution Foundation - Knowledge Service - Knowledge Base Configs
  description: Knowledge base and memory management
  version: 1.0.0
servers:
- url: https://api.evoai.app
  description: Production server
- url: http://localhost:3005
  description: Development server
  variables:
    port:
      default: '3005'
- url: '{customUrl}'
  description: Custom server
  variables:
    customUrl:
      default: https://your-instance.com
      description: Enter your server URL
paths:
  /api/v1/knowledge-base-configs:
    get:
      summary: List Knowledge Base Configs
      description: List all knowledge base configurations for the current account.
      operationId: list_knowledge_base_configs_api_v1_knowledge_base_configs_get
      parameters:
      - name: provider
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ProviderType'
          - type: 'null'
          description: Filter by provider type
          title: Provider
        description: Filter by provider type
      - name: active_only
        in: query
        required: false
        schema:
          type: boolean
          description: Show only active configurations
          default: false
          title: Active Only
        description: Show only active configurations
      responses:
        '200':
          description: Knowledge base configurations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse_KnowledgeBaseConfigListResponse_'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: BAD_REQUEST
                  message: Invalid request parameters
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication token
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to perform this action
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Resource not found
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: GET
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: GET
    post:
      summary: Create Knowledge Base Config Endpoint
      description: Create a new knowledge base configuration.
      operationId: create_knowledge_base_config_endpoint_api_v1_knowledge_base_configs_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseConfigCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse_KnowledgeBaseConfigResponse_'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: BAD_REQUEST
                  message: Invalid input data
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: POST
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication token
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: POST
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to perform this action
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: POST
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Resource not found
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: POST
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs
                  method: POST
  /api/v1/knowledge-base-configs/default/{provider}:
    get:
      summary: Get Default Knowledge Base Config By Provider
      description: Get the default knowledge base configuration for a provider.
      operationId: get_default_knowledge_base_config_by_provider_api_v1_knowledge_base_configs_default__provider__get
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ProviderType'
      responses:
        '200':
          description: Default knowledge base configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse_KnowledgeBaseConfigResponse_'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: BAD_REQUEST
                  message: Invalid request parameters
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/default/{provider}
                  method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication token
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/default/{provider}
                  method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to perform this action
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/default/{provider}
                  method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Default knowledge base configuration not found
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/default/{provider}
                  method: GET
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/default/{provider}
                  method: GET
  /api/v1/knowledge-base-configs/{config_id}:
    get:
      summary: Get Knowledge Base Config By Id
      description: Get a specific knowledge base configuration by ID.
      operationId: get_knowledge_base_config_by_id_api_v1_knowledge_base_configs__config_id__get
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Config Id
      responses:
        '200':
          description: Knowledge base configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse_KnowledgeBaseConfigResponse_'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: BAD_REQUEST
                  message: Invalid request parameters
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication token
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to perform this action
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Knowledge base configuration not found
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: GET
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: GET
    put:
      summary: Update Knowledge Base Config Endpoint
      description: Update an existing knowledge base configuration.
      operationId: update_knowledge_base_config_endpoint_api_v1_knowledge_base_configs__config_id__put
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Config Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseConfigUpdate'
      responses:
        '200':
          description: Knowledge base configuration updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse_KnowledgeBaseConfigResponse_'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: BAD_REQUEST
                  message: Invalid input data
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: PUT
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication token
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: PUT
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to perform this action
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: PUT
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Knowledge base configuration not found
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: PUT
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: PUT
    delete:
      summary: Delete Knowledge Base Config Endpoint
      description: Delete a knowledge base configuration.
      operationId: delete_knowledge_base_config_endpoint_api_v1_knowledge_base_configs__config_id__delete
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Config Id
      responses:
        '200':
          description: Knowledge base configuration deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Knowledge base configuration deleted successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: BAD_REQUEST
                  message: Invalid request parameters
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: DELETE
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication token
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: DELETE
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to perform this action
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: DELETE
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Knowledge base configuration not found
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: DELETE
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}
                  method: DELETE
  /api/v1/knowledge-base-configs/{config_id}/test:
    post:
      summary: Test Knowledge Base Config Connection Endpoint
      description: Test connection to a knowledge base configuration.
      operationId: test_knowledge_base_config_connection_endpoint_api_v1_knowledge_base_configs__config_id__test_post
      parameters:
      - name: config_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Config Id
      responses:
        '200':
          description: Connection test completed
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: BAD_REQUEST
                  message: Unsupported provider
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}/test
                  method: POST
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication token
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}/test
                  method: POST
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: Insufficient permissions to perform this action
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}/test
                  method: POST
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Knowledge base configuration not found
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}/test
                  method: POST
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                  path: /api/v1/knowledge-base-configs/{config_id}/test
                  method: POST
components:
  schemas:
    ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Success indicator
          default: false
        error:
          $ref: '#/components/schemas/ErrorInfo'
        meta:
          $ref: '#/components/schemas/MetaInfoError'
          description: Metadata
      type: object
      required:
      - error
      - meta
      title: ErrorResponse
      description: 'Standard error response schema matching error_response() return format.


        This schema matches the structure returned by error_response() function,

        which always uses ErrorInfo for the error field.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    KnowledgeBaseConfigCreate:
      properties:
        provider:
          $ref: '#/components/schemas/ProviderType'
          description: Provider type (pinecone or qdrant)
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: Friendly name for the configuration
        is_active:
          type: boolean
          title: Is Active
          description: Whether the configuration is active
          default: true
        is_default:
          type: boolean
          title: Is Default
          description: Whether this is the default configuration for the account
          default: false
        config:
          additionalProperties: true
          type: object
          title: Config
          description: Provider-specific configuration
      type: object
      required:
      - provider
      - name
      - config
      title: KnowledgeBaseConfigCreate
      description: Schema for creating a knowledge base configuration
    KnowledgeBaseConfigUpdate:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Name
          description: Friendly name
        is_active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Active
          description: Whether the configuration is active
        is_default:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Default
          description: Whether this is the default configuration
        config:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Config
          description: Provider-specific configuration
      type: object
      title: KnowledgeBaseConfigUpdate
      description: Schema for updating a knowledge base configuration
    ProviderType:
      type: string
      enum:
      - pinecone
      - qdrant
      - openai
      - redis
      title: ProviderType
      description: Supported knowledge base provider types
    SuccessResponse_KnowledgeBaseConfigListResponse_:
      properties:
        success:
          type: boolean
          title: Success
          description: Success indicator
          default: true
        data:
          $ref: '#/components/schemas/KnowledgeBaseConfigListResponse'
          description: Response payload
        meta:
          $ref: '#/components/schemas/MetaInfo'
          description: Metadata
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Optional success message
      type: object
      required:
      - data
      - meta
      title: SuccessResponse[KnowledgeBaseConfigListResponse]
    SuccessResponse_KnowledgeBaseConfigResponse_:
      properties:
        success:
          type: boolean
          title: Success
          description: Success indicator
          default: true
        data:
          $ref: '#/components/schemas/KnowledgeBaseConfigResponse'
          description: Response payload
        meta:
          $ref: '#/components/schemas/MetaInfo'
          description: Metadata
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Optional success message
      type: object
      required:
      - data
      - meta
      title: SuccessResponse[KnowledgeBaseConfigResponse]