openapi: 3.0.2
info:
  title: Retrieval Plugin API
  description: A retrieval API for querying and filtering documents based on natural language queries and metadata
  version: 1.0.0
  servers:
    - url: https://your-app-url.com
paths:
  /query:
    post:
      summary: Query
      description: This endpoint accepts an array of search query objects, each containing a natural language query string ("query") and an optional metadata filter ("filter"). Filters can help refine search results based on criteria such as document source or time period, but are not necessary in most cases. You can send multiple queries to compare information from different sources or break down complex questions into sub-questions. If you receive a ResponseTooLargeError, try splitting up the queries into multiple calls to this endpoint.
      operationId: query_query_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryRequest"
        required: true
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryResponse"
        "422":
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPValidationError"
      security:
        - HTTPBearer: []
components:
  schemas:
    DocumentChunkMetadata:
      title: DocumentChunkMetadata
      type: object
      properties:
        source:
          $ref: "#/components/schemas/Source"
        source_id:
          title: Source Id
          type: string
        url:
          title: Url
          type: string
        created_at:
          title: Created At
          type: string
        author:
          title: Author
          type: string
        document_id:
          title: Document Id
          type: string
    DocumentChunkWithScore:
      title: DocumentChunkWithScore
      required:
        - text
        - metadata
        - score
      type: object
      properties:
        id:
          title: Id
          type: string
        text:
          title: Text
          type: string
        metadata:
          $ref: "#/components/schemas/DocumentChunkMetadata"
        embedding:
          title: Embedding
          type: array
          items:
            type: number
        score:
          title: Score
          type: number
    DocumentMetadataFilter:
      title: DocumentMetadataFilter
      type: object
      properties:
        document_id:
          title: Document Id
          type: string
        source:
          $ref: "#/components/schemas/Source"
        source_id:
          title: Source Id
          type: string
        author:
          title: Author
          type: string
        start_date:
          title: Start Date
          type: string
        end_date:
          title: End Date
          type: string
    HTTPValidationError:
      title: HTTPValidationError
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: "#/components/schemas/ValidationError"
    Query:
      title: Query
      required:
        - query
      type: object
      properties:
        query:
          title: Query
          type: string
        filter:
          $ref: "#/components/schemas/DocumentMetadataFilter"
        top_k:
          title: Top K
          type: integer
          default: 3
    QueryRequest:
      title: QueryRequest
      required:
        - queries
      type: object
      properties:
        queries:
          title: Queries
          type: array
          items:
            $ref: "#/components/schemas/Query"
    QueryResponse:
      title: QueryResponse
      required:
        - results
      type: object
      properties:
        results:
          title: Results
          type: array
          items:
            $ref: "#/components/schemas/QueryResult"
    QueryResult:
      title: QueryResult
      required:
        - query
        - results
      type: object
      properties:
        query:
          title: Query
          type: string
        results:
          title: Results
          type: array
          items:
            $ref: "#/components/schemas/DocumentChunkWithScore"
    Source:
      title: Source
      enum:
        - email
        - file
        - chat
      type: string
      description: An enumeration.
    ValidationError:
      title: ValidationError
      required:
        - loc
        - msg
        - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer