Qubrid AI RAG Queries API

openapi: 3.2.0
info:
  title: Qubrid AI RAG RAG Queries 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: 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:
    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.
    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.
    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
  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