openapi: 3.1.0
info:
  title: Qubrid AI Compute Chat Completions Knowledge Bases API
  description: The Qubrid AI Compute API provides programmatic access to GPU cloud infrastructure including NVIDIA H100, H200, and B200 accelerators. Developers can provision and manage GPU instances for AI and machine learning workloads through API calls. The service supports on-demand compute for training, fine-tuning, and batch inference jobs, with usage-based billing and enterprise features such as team collaboration and usage tracking. Instances can be accessed via SSH, Jupyter notebooks, or Visual Studio Code, and support quick-deploy templates for popular frameworks including PyTorch, TensorFlow, ComfyUI, n8n, and Langflow.
  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 Compute 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:
    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.
    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.
    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