---
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: JobService
    description: Operations related to jobs
  - name: JobCollectorService
    description: Operations related to job collectors
  - name: JobDocumentsService
    description: Operations related to job 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/JobClient"
        "400":
          description: Invalid request parameters.
        "404":
          description: Client not found.
    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.
        "404":
          description: Client not found

  /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.
        "404":
          description: Query not found.
    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.
        "404":
          description: Query not found.
    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.
        "404":
          description: Query not found.

  /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.

  /job:
    post:
      operationId: createJob
      tags:
        - JobService
      summary: Create a new job
      description: Creates a new job with the provided details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobCreate"
      responses:
        "201":
          description: Job created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdMessage"
        "400":
          description: Invalid request body.

  /job/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The job ID.
    get:
      operationId: getJob
      tags:
        - JobService
      summary: Get a job by ID
      description: Retrieves a specific job by its ID.
      responses:
        "200":
          description: Job details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          description: Invalid request parameters.
        "404":
          description: Job not found.
    patch:
      operationId: updateJob
      tags:
        - JobService
      summary: Update a job
      description: Updates an existing job with new details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobUpdate"
      responses:
        "204":
          description: Job updated successfully.
        "400":
          description: Invalid request body.
        "404":
          description: Job not found.

  /job/{id}/status:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The job ID for the collector.
    get:
      operationId: getJobStatusByJobId
      tags:
        - JobCollectorService
      summary: Get job status by job ID
      description: Retrieves the job status by its job ID.
      responses:
        "200":
          description: Job status details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusBody"
        "400":
          description: Invalid request parameters.
        "404":
          description: Job not found.

  /job/{id}/collector:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The job ID for the collector.
    get:
      operationId: getJobCollectorByJobId
      tags:
        - JobCollectorService
      summary: Get a job collector by ID
      description: Retrieves a specific job collector by its ID.
      responses:
        "200":
          description: Job collector details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobCollector"
        "404":
          description: Job collector not found.
    patch:
      operationId: updateJobCollectorByJobId
      tags:
        - JobCollectorService
      summary: Update a job collector
      description: Updates an existing job collector with new details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobCollectorUpdate"
      responses:
        "204":
          description: Job collector updated successfully.
        "400":
          description: Invalid request body.
        "404":
          description: Job collector not found.

  /job/{id}/documents:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The job ID for the documents.
    get:
      operationId: listDocumentsByJobId
      tags:
        - JobDocumentsService
      summary: List the documents for a job
      description: Retrieves the list of documents by the job ID.
      responses:
        "200":
          description: Job documents list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListDocuments"
        "404":
          description: Job not found.

  /job/export:
    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.
        "404":
          description: Job not found.

  /job/{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"
        "404":
          description: Export job not found.

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

    JobClient:
      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

    JobStatus:
      type: string
      enum:
        - IN_SYNC
        - NOT_SYNCED
      description: Specifies the status of a job.

    Job:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The job id
        client_id:
          type: string
          format: uuid
          description: The client id the job belongs to
        can_sync:
          type: boolean
          description: Specifies whether the job is actively syncing
      required:
        - id
        - client_id
        - can_sync

    JobStatusBody:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
          description: The job id
        status:
          $ref: "#/components/schemas/JobStatus"
      required:
        - job_id
        - status

    JobCreate:
      type: object
      properties:
        client_id:
          type: string
          format: uuid
          description: The client id the job belongs to
      required:
        - client_id

    JobUpdate:
      type: object
      properties:
        can_sync:
          type: boolean
          description: Specifies whether the job is actively syncing

    ListDocuments:
      type: array
      description: The documents in the job.
      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

    JobCollector:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
          description: The ID of the associated job.
        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 job collector.
          items:
            $ref: "#/components/schemas/JobCollectorField"
      description: JobCollector model.
      required:
        - job_id
        - fields
        - minimum_cleaner_version
        - minimum_text_version
        - latest_version
        - active_version

    JobCollectorUpdate:
      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 job collector.
          items:
            $ref: "#/components/schemas/JobCollectorField"
      description: Payload for updating a JobCollector.

    JobCollectorField:
      type: object
      description: The field properties for the job 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:
        job_id:
          type: string
          format: uuid
          description: The job id of the query results to be exported.
        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.
      required:
        - job_id

    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 job states.

    ExportDetails:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
          description: The job 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}/{clientid}/{jobid}/{timestamp}_{exportid}.zip
      description: Payload for export trigger response.
      required:
        - job_id
        - status