---
openapi: 3.0.3
info:
  title: Query Orchestration API
  description: API documentation for the Query Orchestration services.
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
    description: Production server
tags:
  - name: ClientService
    description: Operations related to clients
  - name: CollectorService
    description: Operations related to collectors
  - name: DocumentsService
    description: Operations related to documents
  - name: QueryService
    description: Operations related to queries
  - name: ExportService
    description: Operations related to exports

paths:
  /client:
    post:
      operationId: createClient
      tags:
        - ClientService
      summary: Create a new client
      description: Creates a new client with the provided details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClientCreate"
      responses:
        "201":
          description: Client created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdMessage"
        "400":
          description: Invalid request body.

  /client/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the client to retrieve.
    get:
      operationId: getClient
      tags:
        - ClientService
      summary: Get a client by ID
      description: Retrieves a specific client by its ID.
      responses:
        "200":
          description: Client details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocClient"
        "400":
          description: Invalid request parameters.
    patch:
      operationId: updateClient
      tags:
        - ClientService
      summary: Update a client
      description: Updates an existing client with new details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClientUpdate"
      responses:
        "200":
          description: Client updated successfully.
        "400":
          description: Invalid request body.

  /query:
    get:
      operationId: listQueries
      tags:
        - QueryService
      summary: List queries
      description: Retrieves a list of queries based on filter criteria.
      responses:
        "200":
          description: A list of queries.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListQueries"
        "400":
          description: Invalid request parameters.
    post:
      operationId: createQuery
      tags:
        - QueryService
      summary: Create a new query
      description: Creates a new query with the provided details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryCreate"
      responses:
        "201":
          description: Query created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdMessage"
        "400":
          description: Invalid request body.

  /query/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the query.
    get:
      operationId: getQuery
      tags:
        - QueryService
      summary: Get a query by ID
      description: Retrieves a specific query by its ID.
      responses:
        "200":
          description: Query details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Query"
        "400":
          description: Invalid request parameters.
    patch:
      operationId: updateQuery
      tags:
        - QueryService
      summary: Update a query
      description: Updates an existing query with new details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryUpdate"
      responses:
        "200":
          description: Query updated successfully.
        "400":
          description: Invalid request body.

  /query/{id}/test:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the query.
    post:
      operationId: testQuery
      tags:
        - QueryService
      summary: Test a query
      description: Executes a test run of a query with the provided parameters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryTestRequest"
      responses:
        "200":
          description: Test result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryTestResponse"
        "400":
          description: Invalid request body.

  /client/{id}/status:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The client id.
    get:
      operationId: getStatusByClientId
      tags:
        - ClientService
      summary: Get client sync status
      description: Retrieves the sync status by its client ID.
      responses:
        "200":
          description: Client status details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientStatusBody"
        "400":
          description: Invalid request parameters.

  /client/{id}/collector:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The client ID for the collector.
    get:
      operationId: getCollectorByClientId
      tags:
        - CollectorService
      summary: Get a collector by client ID
      description: Retrieves a specific collector by its client ID.
      responses:
        "200":
          description: Collector details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collector"
        "400":
          description: Invalid body.
    patch:
      operationId: setCollectorByClientId
      tags:
        - CollectorService
      summary: Set a collector
      description: Set client collector with new details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectorSet"
      responses:
        "204":
          description: Collector set successfully.
        "400":
          description: Invalid request body.

  /client/{id}/documents:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The client ID for the documents.
    get:
      operationId: listDocumentsByClientId
      tags:
        - DocumentsService
      summary: List the documents for a client
      description: Retrieves the list of documents by the client ID.
      responses:
        "200":
          description: Client documents list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListDocuments"
        "400":
          description: Invalid request body.

  /client/{id}/export:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the export.
    get:
      operationId: exportState
      tags:
        - ExportService
      summary: Check export state.
      description: Checks the current state of an export.
      responses:
        "200":
          description: Export has been completed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportDetails"
        "400":
          description: Invalid body.
    post:
      operationId: triggerExport
      tags:
        - ExportService
      summary: Trigger an export
      description: Initiates the export process.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExportTrigger"
      responses:
        "201":
          description: Export triggered successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdMessage"
        "400":
          description: Invalid request body.

components:
  schemas:
    QueryType:
      type: string
      enum:
        - JSON_EXTRACTOR
        - CONTEXT_FULL
      description: Specifies the type of the query.

    Query:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the query.
        type:
          $ref: "#/components/schemas/QueryType"
        active_version:
          type: integer
          format: int32
          description: The active version of the query.
        latest_version:
          type: integer
          format: int32
          description: The latest version of the query.
        config:
          type: string
          description: Configuration for the query.
        required_queries:
          type: array
          items:
            type: string
            format: uuid
          description: List of required query IDs.
      required:
        - id
        - type
        - active_version
        - latest_version

    ListQueries:
      type: object
      properties:
        queries:
          type: array
          items:
            $ref: "#/components/schemas/Query"
          description: List of queries.
      required:
        - queries

    QueryCreate:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/QueryType"
        config:
          type: string
          description: Configuration for the new query.
        required_queries:
          type: array
          items:
            type: string
            format: uuid
          description: List of required query IDs.
      required:
        - type

    QueryUpdate:
      type: object
      properties:
        config:
          type: string
          description: Updated configuration for the query.
        active_version:
          type: integer
          format: int32
          description: Updated active version.
        required_queries:
          type: array
          items:
            type: string
            format: uuid
          description: Updated list of required query IDs.

    QueryTestRequest:
      type: object
      properties:
        document_id:
          type: string
          format: uuid
          description: ID of the document to test against.
        query_version:
          type: integer
          format: int32
          description: Version of the query to use for testing.
      required:
        - document_id
        - query_version

    QueryTestResponse:
      type: object
      properties:
        value:
          type: string
          description: Result of the query test.
      required:
        - value

    DocClient:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The client id
        name:
          type: string
          description: The client name
        can_sync:
          type: boolean
          description: If the client is allowing active syncs
      required:
        - id
        - name
        - can_sync

    ClientStatus:
      type: string
      enum:
        - IN_SYNC
        - NOT_SYNCED
        - NOT_SYNCING
      description: Specifies the status of a client.

    ClientStatusBody:
      type: object
      properties:
        client_id:
          type: string
          format: uuid
          description: The client id
        status:
          $ref: "#/components/schemas/ClientStatus"
      required:
        - client_id
        - status

    ListDocuments:
      type: array
      description: The documents in the client.
      items:
        $ref: "#/components/schemas/Document"

    Document:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The document id
        bucket:
          type: string
          description: The bucket containing the document
        key:
          type: string
          description: The path to the document
      required:
        - id
        - bucket
        - key

    ClientCreate:
      type: object
      properties:
        name:
          type: string
          description: The client name
      required:
        - name

    ClientUpdate:
      type: object
      properties:
        name:
          type: string
          description: The client name
        can_sync:
          type: boolean
          description: If the client is allowing active syncs

    IdMessage:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for entity.
      required:
        - id

    Collector:
      type: object
      properties:
        client_id:
          type: string
          format: uuid
          description: The ID of the associated client.
        active_version:
          type: integer
          format: int32
          description: The active version of the collector.
        latest_version:
          type: integer
          format: int32
          description: The latest version of the collector.
        minimum_cleaner_version:
          type: integer
          format: int32
          description: The minimum version for the document cleaner.
        minimum_text_version:
          type: integer
          format: int32
          description: The minimum version for the text parser.
        fields:
          type: array
          description: The fields in the collector.
          items:
            $ref: "#/components/schemas/CollectorField"
      description: Collector model.
      required:
        - client_id
        - fields
        - minimum_cleaner_version
        - minimum_text_version
        - latest_version
        - active_version

    CollectorSet:
      type: object
      properties:
        minimum_cleaner_version:
          type: integer
          format: int32
          description: The minimum version for the document cleaner.
        minimum_text_version:
          type: integer
          format: int32
          description: The minimum version for the text parser.
        active_version:
          type: integer
          format: int32
          description: The active version of the collector.
        fields:
          type: array
          description: The fields in the collector.
          items:
            $ref: "#/components/schemas/CollectorField"
      description: Payload for updating a Collector.

    CollectorField:
      type: object
      description: The field properties for the collector.
      properties:
        name:
          type: string
          description: The output field name.
        query_id:
          type: string
          format: uuid
          description: The query id that will populate the result.
      required:
        - name
        - query_id

    ExportTrigger:
      type: object
      properties:
        ingestion_filters:
          type: object
          description: Filter the scope based on ingestion parameters.
          properties:
            start_date:
              type: string
              description: This first date of ingestion.
            end_date:
              type: string
              description: The last date of ingestion.
        field_filters:
          type: array
          description: Filter the scope based on field output values.
          items:
            $ref: "#/components/schemas/FieldFilter"
      description: Payload for triggering an export.

    FieldFilter:
      type: object
      properties:
        field_name:
          type: string
          description: The name of the field in question.
        condition:
          $ref: "#/components/schemas/FieldFilterCondition"
        values:
          type: array
          description: The values useful to the filter.
          items:
            type: string
      description: Filtering a column
      required:
        - field_name
        - condition
        - values

    FieldFilterCondition:
      type: string
      enum:
        - less_than
        - greater_than
        - closed_interval
        - open_interval
        - left_closed_interval
        - right_closed_interval
        - include
        - exclude
      description: The possible field filtering conditions.

    ExportStatus:
      type: string
      enum:
        - completed
        - in_progress
        - failed
      description: The possible export states.

    ExportDetails:
      type: object
      properties:
        client_id:
          type: string
          format: uuid
          description: The client id relative to the export.
        status:
          $ref: "#/components/schemas/ExportStatus"
        output_location:
          type: string
          description: The location in which the export zip file will be found.
          example: |
            s3://{bucket_name}/{external_client_id}/yyyymmdd/{export_id}.csv
      description: Payload for export trigger response.
      required:
        - client_id
        - status