openapi: 3.0.0
info:
  title: Example API
  version: 1.0.1
paths:
  /v1/run:
    post:
      summary: Run a query and get generated text with retrieved passages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: The query string
                result_column:
                  type: string
                  description: The result column name
                  default: generated_texts
              required:
                - query
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - generated_text
                      - retrieved_passage
                    description: |
                      When the type is "generated_text", only "generated_text" is returned.
                      The other fields are None. When the type is "retrieved_passage", only
                      "retrieved_passage" and "passage_index" are returned. The other fields are None.
                  generated_text:
                    type: string
                    nullable: true
                    description: |
                      The generated text, only present when "type" is "generated_text".
                  retrieved_passage:
                    type: object
                    nullable: true
                    properties:
                      content:
                        type: string
                      doc_id:
                        type: string
                      filepath:
                        type: string
                        nullable: true
                      file_page:
                        type: integer
                        nullable: true
                      start_idx:
                        type: integer
                        nullable: true
                      end_idx:
                        type: integer
                        nullable: true
                  passage_index:
                    type: integer
                    nullable: true
                    description: |
                      The index of the retrieved passage, only present when "type" is "retrieved_passage".
                required:
                  - type
                oneOf:
                  - required:
                      - generated_text
                  - required:
                      - retrieved_passage
                      - passage_index
  /v1/retrieve:
    post:
      summary: Retrieve documents based on a query
      operationId: runRetrieveOnly
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: The query string to retrieve documents.
              required:
                - query
      responses:
        '200':
          description: Successful retrieval of documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  passages:
                    type: array
                    items:
                      type: object
                      properties:
                        doc_id:
                          type: string
                          description: The unique identifier for the document.
                        content:
                          type: string
                          description: The content of the retrieved document.
                        score:
                          type: number
                          format: float
                          description: The score of the retrieved document.
        '400':
          description: Invalid request due to missing query parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message explaining the issue.
  /v1/stream:
    post:
      summary: Stream generated text with retrieved passages
      description: >
        This endpoint streams the generated text line by line. The `retrieved_passage`
        is sent first, followed by the `result` streamed incrementally.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: The query string
                result_column:
                  type: string
                  description: The result column name
                  default: generated_texts
              required:
                - query
      responses:
        '200':
          description: Successful response with streaming
          content:
            text/event-stream:
              schema:
                type: object
                properties:
                  result:
                    oneOf:
                      - type: string
                      - type: array
                        items:
                          type: string
                    description: The result text or list of texts (streamed line by line)
                  retrieved_passage:
                    type: array
                    items:
                      type: object
                      properties:
                        content:
                          type: string
                        doc_id:
                          type: string
                        filepath:
                          type: string
                        nullable: true
                        file_page:
                          type: integer
                          nullable: true
                        start_idx:
                          type: integer
                          nullable: true
                        end_idx:
                          type: integer
                          nullable: true

  /version:
    get:
      summary: Get the API version
      description: Returns the current version of the API as a string.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    description: The version of the API