openapi: 3.1.0
info:
  title: Qubrid AI Compute Chat Completions RAG Queries 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: RAG Queries
  description: Query a knowledge base using natural language with retrieval-augmented generation. The API retrieves relevant document chunks from the knowledge base and uses them as context for generating accurate, grounded responses through a large language model.
paths:
  /rag/query:
    post:
      operationId: queryRag
      summary: Query with RAG
      description: Performs a retrieval-augmented generation query against a specified knowledge base. The API retrieves the most relevant document chunks based on semantic similarity to the query, then uses them as context for a large language model to generate an accurate, grounded response. The response includes both the generated answer and the source document references used.
      tags:
      - RAG Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RagQueryRequest'
      responses:
        '200':
          description: Successfully generated a RAG response grounded in the knowledge base documents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RagQueryResponse'
        '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'
        '404':
          description: The specified knowledge base was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RagQueryRequest:
      type: object
      required:
      - knowledge_base_id
      - query
      - model
      properties:
        knowledge_base_id:
          type: string
          description: The identifier of the knowledge base to query against.
        query:
          type: string
          description: The natural language question or query to answer using retrieval-augmented generation.
        model:
          type: string
          description: The identifier of the large language model to use for generating the response based on retrieved context.
        top_k:
          type: integer
          description: The number of most relevant document chunks to retrieve and use as context for the response.
          minimum: 1
          maximum: 20
          default: 5
        temperature:
          type: number
          description: Sampling temperature for the response generation. Lower values produce more focused and deterministic responses.
          minimum: 0
          maximum: 2
          default: 0.7
        max_tokens:
          type: integer
          description: The maximum number of tokens to generate in the response.
          minimum: 1
        include_sources:
          type: boolean
          description: Whether to include source document references in the response.
          default: true
    SourceReference:
      type: object
      properties:
        document_id:
          type: string
          description: The identifier of the source document.
        document_name:
          type: string
          description: The name of the source document.
        chunk_text:
          type: string
          description: The text content of the retrieved chunk used as context.
        relevance_score:
          type: number
          description: The semantic similarity score between the query and this chunk, expressed as a value between 0 and 1.
          minimum: 0
          maximum: 1
    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.
    RagQueryResponse:
      type: object
      properties:
        answer:
          type: string
          description: The generated response grounded in the retrieved document context.
        model:
          type: string
          description: The model used to generate the response.
        sources:
          type: array
          description: A list of source document references that were used as context for generating the response.
          items:
            $ref: '#/components/schemas/SourceReference'
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
              description: The number of tokens in the prompt including retrieved context.
            completion_tokens:
              type: integer
              description: The number of tokens in the generated response.
            total_tokens:
              type: integer
              description: The total number of tokens used.
  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