Qubrid AI Knowledge Bases API

openapi: 3.2.0
info:
  title: Qubrid AI RAG Knowledge Bases API
  description: The Qubrid AI RAG API provides retrieval-augmented generation capabilities that allow developers to upload departmental or enterprise data and query it using large language models.
  version: 1.0.0
  contact:
    name: Qubrid AI Support
    url: https://www.qubrid.com/contact
  termsOfService: https://www.qubrid.com/terms-of-service
servers:
- url: https://platform.qubrid.com/api/v1
  description: Qubrid AI RAG Production Server
security:
- bearerAuth: []
tags:
- name: Knowledge Bases
  description: Create and manage knowledge bases that store enterprise and departmental data for retrieval-augmented generation. Each knowledge base contains ingested documents that are chunked, embedded, and stored in a vector database for semantic search during inference.
paths:
  /rag/knowledge-bases:
    get:
      operationId: listKnowledgeBases
      summary: List knowledge bases
      description: Returns a list of all knowledge bases associated with the authenticated user's account, including their name, document count, and processing status.
      tags:
      - Knowledge Bases
      responses:
        '200':
          description: Successfully retrieved the list of knowledge bases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseList'
        '401':
          description: Authentication failed due to a missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createKnowledgeBase
      summary: Create a knowledge base
      description: Creates a new knowledge base for storing and retrieving enterprise documents. The knowledge base serves as a container for documents that will be chunked, embedded, and indexed for retrieval-augmented generation queries.
      tags:
      - Knowledge Bases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKnowledgeBaseRequest'
      responses:
        '201':
          description: Successfully created the knowledge base.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '400':
          description: The request was malformed or contained invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication failed due to a missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /rag/knowledge-bases/{knowledge_base_id}:
    get:
      operationId: getKnowledgeBase
      summary: Retrieve a knowledge base
      description: Returns details about a specific knowledge base including its configuration, document count, total chunk count, and embedding model used.
      tags:
      - Knowledge Bases
      parameters:
      - $ref: '#/components/parameters/KnowledgeBaseId'
      responses:
        '200':
          description: Successfully retrieved the knowledge base details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '401':
          description: Authentication failed due to a missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The specified knowledge base was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteKnowledgeBase
      summary: Delete a knowledge base
      description: Permanently deletes a knowledge base and all of its associated documents, embeddings, and vector index data. This action cannot be undone.
      tags:
      - Knowledge Bases
      parameters:
      - $ref: '#/components/parameters/KnowledgeBaseId'
      responses:
        '204':
          description: Successfully deleted the knowledge base.
        '401':
          description: Authentication failed due to a missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The specified knowledge base was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    KnowledgeBase:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the knowledge base.
        name:
          type: string
          description: The display name of the knowledge base.
        description:
          type: string
          description: A description of the knowledge base and the type of data it contains.
        embedding_model:
          type: string
          description: The embedding model used to generate vector representations of document chunks in this knowledge base.
        document_count:
          type: integer
          description: The total number of documents in the knowledge base.
        chunk_count:
          type: integer
          description: The total number of chunks across all documents in the knowledge base.
        status:
          type: string
          enum:
          - ready
          - processing
          - error
          description: The current status of the knowledge base. Ready means all documents have been processed, processing means documents are being ingested, and error means an issue occurred.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the knowledge base was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the knowledge base was last updated.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: A human-readable error message describing what went wrong.
            type:
              type: string
              description: The type of error that occurred.
            code:
              type: string
              description: A machine-readable error code.
    CreateKnowledgeBaseRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: A display name for the knowledge base.
          maxLength: 256
        description:
          type: string
          description: An optional description of the knowledge base and the type of data it will contain.
          maxLength: 1024
        embedding_model:
          type: string
          description: The embedding model to use for generating vector representations of document chunks. If not specified, a default embedding model will be used.
        chunk_size:
          type: integer
          description: The target size of each document chunk in tokens. Smaller chunks provide more granular retrieval while larger chunks provide more context.
          minimum: 64
          maximum: 4096
          default: 512
        chunk_overlap:
          type: integer
          description: The number of tokens of overlap between consecutive document chunks to preserve context at chunk boundaries.
          minimum: 0
          maximum: 1024
          default: 64
    KnowledgeBaseList:
      type: object
      properties:
        data:
          type: array
          description: A list of knowledge base objects.
          items:
            $ref: '#/components/schemas/KnowledgeBase'
  parameters:
    KnowledgeBaseId:
      name: knowledge_base_id
      in: path
      required: true
      description: The unique identifier of the knowledge base.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: QUBRID_API_KEY
      description: Qubrid AI API key passed as a bearer token in the Authorization header. Obtain your API key from the Qubrid AI platform dashboard at https://platform.qubrid.com.
externalDocs:
  description: Qubrid AI Documentation
  url: https://docs.platform.qubrid.com