query-orchestration/serviceAPIs/queryAPI.yaml

---
openapi: 3.0.3
info:
  title: Query Orchestration API
  description: API documentation for the Query Orchestration services.
  version: 0.0.1
  contact:
    email: mmcguinness@aarete.com
    name: Michael McGuinness
    url: doczy.com
  license:
    name: unlicensed
    url: "www.example.com"
servers:
  - url: https://doczy.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: QueryAPI
    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.
      security:
        - placeholderAuth: []
      requestBody:
        description: The details required to create a client
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClientCreate"
      responses:
        "201":
          description: Client created successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientIDBody"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /client/{id}:
    parameters:
      - $ref: "#/components/parameters/ClientID"
    get:
      operationId: getClient
      tags:
        - ClientService
      summary: Get a client by ID
      description: Retrieves a specific client by its ID.
      security:
        - placeholderAuth: []
      responses:
        "200":
          description: Client details.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocClient"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      operationId: updateClient
      tags:
        - ClientService
      summary: Update a client
      description: Updates an existing client with new details.
      security:
        - placeholderAuth: []
      requestBody:
        description: The details to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClientUpdate"
      responses:
        "200":
          description: Client updated successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /query:
    get:
      operationId: listQueries
      tags:
        - QueryAPI
      summary: List queries
      description: Retrieves a list of queries based on filter criteria.
      security:
        - placeholderAuth: []
      responses:
        "200":
          description: A list of queries.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListQueries"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      operationId: createQuery
      tags:
        - QueryAPI
      summary: Create a new query
      description: Creates a new query with the provided details.
      security:
        - placeholderAuth: []
      requestBody:
        description: The details required to create a query
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryCreate"
      responses:
        "201":
          description: Query created successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdMessage"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /query/{id}:
    parameters:
      - $ref: "#/components/parameters/QueryID"
    get:
      operationId: getQuery
      tags:
        - QueryAPI
      summary: Get a query by ID
      description: Retrieves a specific query by its ID.
      security:
        - placeholderAuth: []
      responses:
        "200":
          description: Query details.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Query"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      operationId: updateQuery
      tags:
        - QueryAPI
      summary: Update a query
      description: Updates an existing query with new details.
      security:
        - placeholderAuth: []
      requestBody:
        description: The update values for the desired query.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryUpdate"
      responses:
        "200":
          description: Query updated successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /query/{id}/test:
    parameters:
      - $ref: "#/components/parameters/QueryID"
    post:
      operationId: testQuery
      tags:
        - QueryAPI
      summary: Test a query
      description: Executes a test run of a query with the provided parameters.
      security:
        - placeholderAuth: []
      requestBody:
        description: The query test requirements.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryTestRequest"
      responses:
        "200":
          description: Test result.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryTestResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /client/{id}/status:
    parameters:
      - $ref: "#/components/parameters/ClientID"
    get:
      operationId: getStatusByClientId
      tags:
        - ClientService
      summary: Get client sync status
      description: Retrieves the sync status by its client ID.
      security:
        - placeholderAuth: []
      responses:
        "200":
          description: Client status details.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientStatusBody"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /client/{id}/collector:
    parameters:
      - $ref: "#/components/parameters/ClientID"
    get:
      operationId: getCollectorByClientId
      tags:
        - CollectorService
      summary: Get a collector by client ID
      description: Retrieves a specific collector by its client ID.
      security:
        - placeholderAuth: []
      responses:
        "200":
          description: Collector details.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collector"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      operationId: setCollectorByClientId
      tags:
        - CollectorService
      summary: Set a collector
      description: Set client collector with new details.
      security:
        - placeholderAuth: []
      requestBody:
        description: The details to be set for the collector.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectorSet"
      responses:
        "204":
          description: Collector set successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /client/{id}/documents:
    parameters:
      - $ref: "#/components/parameters/ClientID"
    get:
      operationId: listDocumentsByClientId
      tags:
        - DocumentsService
      summary: List the documents for a client
      description: Retrieves the list of documents by the client ID.
      security:
        - placeholderAuth: []
      responses:
        "200":
          description: Client documents list.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListDocuments"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /document/{id}:
    parameters:
      - $ref: "#/components/parameters/DocumentID"
    get:
      operationId: getDocument
      tags:
        - DocumentsService
      summary: Get document details by its id
      description: Retrieves the details of a document by its id.
      security:
        - placeholderAuth: []
      responses:
        "200":
          description: Document details.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Document"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /client/{id}/export:
    parameters:
      - $ref: "#/components/parameters/ClientID"
    post:
      operationId: triggerExport
      tags:
        - ExportService
      summary: Trigger an export
      description: Initiates the export process.
      security:
        - placeholderAuth: []
      requestBody:
        description: The export requirements.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExportTrigger"
      responses:
        "201":
          description: Export triggered successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdMessage"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /export/{id}:
    parameters:
      - $ref: "#/components/parameters/ExportID"
    get:
      operationId: exportState
      tags:
        - ExportService
      summary: Check export state.
      description: Checks the current state of an export.
      security:
        - placeholderAuth: []
      responses:
        "200":
          description: Export has been completed.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportDetails"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

components:
  parameters:
    ClientID:
      in: path
      name: id
      required: true
      schema:
        $ref: "#/components/schemas/ClientID"
      description: The client ID.

    ExportID:
      in: path
      name: id
      required: true
      schema:
        $ref: "#/components/schemas/ExportID"
      description: The export ID.

    QueryID:
      in: path
      name: id
      required: true
      schema:
        $ref: "#/components/schemas/QueryID"
      description: The ID of the query.

    DocumentID:
      in: path
      name: id
      required: true
      schema:
        $ref: "#/components/schemas/DocumentID"
      description: The document ID.

  headers:
    RateLimit:
      schema:
        type: string
        pattern: "^[0-9]+;window=[0-9]+$"
        maxLength: 32
        example: 100;window=60
      description: Rate limit information in format "limit;window=time-window"
      example: "100;window=10"

  securitySchemes:
    placeholderAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: "Placeholder security scheme for future implementation"

  responses:
    InvalidRequest:
      description: Invalid request body.
      headers:
        RateLimit:
          $ref: "#/components/headers/RateLimit"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

    InternalError:
      description: Internal server error.
      headers:
        RateLimit:
          $ref: "#/components/headers/RateLimit"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

    TooManyRequests:
      description: Response upon too many requests.
      headers:
        RateLimit:
          $ref: "#/components/headers/RateLimit"
        Retry-After:
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 86400
          description: Number of seconds before trying again.
          example: 120
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

    Unauthorized:
      description: Response when unauthorized.
      headers:
        RateLimit:
          $ref: "#/components/headers/RateLimit"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

  schemas:
    ClientID:
      type: string
      description: The client external id
      example: AAA
      maxLength: 36
      pattern: "^.+$"

    ClientUID:
      type: string
      format: uuid
      description: The client internal unique id
      example: 0195853c-8fdd-77cd-b36c-255241bddd33
      maxLength: 36

    QueryID:
      type: string
      format: uuid
      description: The query id.
      example: 019580df-ef65-7676-8de9-94435a93337a
      maxLength: 36

    DocumentID:
      type: string
      format: uuid
      description: The document id.
      example: 019580df-b3f8-7348-9ab1-1e55b3f18ed7
      maxLength: 36

    ExportID:
      type: string
      format: uuid
      description: The export id.
      example: 019580de-4d51-713c-98ee-464e83811f13
      maxLength: 36

    ClientName:
      type: string
      description: The client name
      example: AArete
      maxLength: 256
      pattern: "^.+$"

    ClientCanSync:
      type: boolean
      description: If the client is allowing active syncs

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

    QueryConfig:
      type: string
      description: Configuration for the query.
      maxLength: 2048
      pattern: '^\{.*\}$'

    Query:
      description: A logic unit of execution.
      type: object
      properties:
        id:
          $ref: "#/components/schemas/QueryID"
        type:
          $ref: "#/components/schemas/QueryType"
        active_version:
          $ref: "#/components/schemas/Version"
        latest_version:
          $ref: "#/components/schemas/Version"
        config:
          $ref: "#/components/schemas/QueryConfig"
        required_queries:
          $ref: "#/components/schemas/RequiredQueryIDs"
      required:
        - id
        - type
        - active_version
        - latest_version

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

    QueryCreate:
      description: The parameters required to create a query.
      type: object
      properties:
        type:
          $ref: "#/components/schemas/QueryType"
        config:
          $ref: "#/components/schemas/QueryConfig"
        required_queries:
          $ref: "#/components/schemas/RequiredQueryIDs"
      required:
        - type

    RequiredQueryIDs:
      type: array
      maxItems: 256
      items:
        $ref: "#/components/schemas/QueryID"
      description: List of required query IDs.

    QueryUpdate:
      description: The properties that may be updated for a query.
      type: object
      properties:
        config:
          $ref: "#/components/schemas/QueryConfig"
        active_version:
          $ref: "#/components/schemas/Version"
        required_queries:
          $ref: "#/components/schemas/RequiredQueryIDs"

    QueryTestRequest:
      description: The properties for a query test request.
      type: object
      properties:
        document_id:
          $ref: "#/components/schemas/DocumentID"
        query_version:
          $ref: "#/components/schemas/Version"
      required:
        - document_id
        - query_version

    QueryTestResponse:
      description: The response from a query test.
      type: object
      properties:
        value:
          type: string
          description: Result of the query test.
          pattern: "^.+$"
          maxLength: 2048
      required:
        - value

    DocClient:
      description: The properties of a client.
      type: object
      properties:
        uid:
          $ref: "#/components/schemas/ClientUID"
        id:
          $ref: "#/components/schemas/ClientID"
        name:
          $ref: "#/components/schemas/ClientName"
        can_sync:
          $ref: "#/components/schemas/ClientCanSync"
      required:
        - id
        - uid
        - name
        - can_sync

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

    ClientStatusBody:
      description: A client status information object.
      type: object
      properties:
        status:
          $ref: "#/components/schemas/ClientStatus"
      required:
        - status

    ClientIDBody:
      description: The client id.
      type: object
      properties:
        id:
          $ref: "#/components/schemas/ClientID"
      required:
        - id

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

    Hash:
      type: string
      description: The document hash
      maxLength: 2048
      pattern: "^.+$"

    DocumentSummary:
      description: The document summary properties.
      type: object
      properties:
        id:
          $ref: "#/components/schemas/DocumentID"
        hash:
          $ref: "#/components/schemas/Hash"
      required:
        - id
        - hash

    Document:
      description: The document properties.
      type: object
      properties:
        id:
          $ref: "#/components/schemas/DocumentID"
        client_id:
          $ref: "#/components/schemas/ClientID"
        hash:
          $ref: "#/components/schemas/Hash"
        fields:
          type: object
          description: "The fields and the value for the document"
          example:
            property1: "string value"
            property2: 42
            property3: true
            property5: [1, 2, 3]
      required:
        - id
        - client_id
        - hash
        - fields

    ClientCreate:
      description: The properties for creation.
      type: object
      properties:
        id:
          $ref: "#/components/schemas/ClientID"
        name:
          $ref: "#/components/schemas/ClientName"
      required:
        - id
        - name

    ClientUpdate:
      description: The properties that may be updated.
      type: object
      properties:
        name:
          $ref: "#/components/schemas/ClientName"
        can_sync:
          $ref: "#/components/schemas/ClientCanSync"

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

    CodeVersion:
      type: integer
      format: int64
      minimum: 1
      maximum: 9223372036854775808
      description: The desired code version.

    Version:
      type: integer
      format: int32
      minimum: 0
      maximum: 2147483647
      description: The desired version.

    Collector:
      type: object
      properties:
        client_id:
          $ref: "#/components/schemas/ClientID"
        active_version:
          $ref: "#/components/schemas/Version"
        latest_version:
          $ref: "#/components/schemas/Version"
        minimum_cleaner_version:
          $ref: "#/components/schemas/CodeVersion"
        minimum_text_version:
          $ref: "#/components/schemas/CodeVersion"
        fields:
          $ref: "#/components/schemas/CollectorFields"
      description: Collector model.
      required:
        - client_id
        - fields
        - minimum_cleaner_version
        - minimum_text_version
        - latest_version
        - active_version

    CollectorFields:
      type: array
      maxItems: 256
      description: The fields in the collector.
      items:
        $ref: "#/components/schemas/CollectorField"

    CollectorSet:
      type: object
      properties:
        minimum_cleaner_version:
          $ref: "#/components/schemas/CodeVersion"
        minimum_text_version:
          $ref: "#/components/schemas/CodeVersion"
        active_version:
          $ref: "#/components/schemas/Version"
        fields:
          $ref: "#/components/schemas/CollectorFields"
      description: Payload for updating a Collector.

    CollectorFieldName:
      type: string
      pattern: "^.+$"
      maxLength: 256
      description: The output field name.

    CollectorField:
      type: object
      description: The field properties for the collector.
      properties:
        name:
          $ref: "#/components/schemas/CollectorFieldName"
        query_id:
          $ref: "#/components/schemas/QueryID"
      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
              format: date-time
              maxLength: 32
              description: This first date of ingestion.
            end_date:
              type: string
              format: date-time
              maxLength: 32
              description: The last date of ingestion.
        field_filters:
          type: array
          maxItems: 256
          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:
          $ref: "#/components/schemas/CollectorFieldName"
        condition:
          $ref: "#/components/schemas/FieldFilterCondition"
        values:
          type: array
          description: The values useful to the filter.
          maxItems: 100
          items:
            type: string
            pattern: "^.+$"
            maxLength: 256
      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:
          $ref: "#/components/schemas/ClientID"
        status:
          $ref: "#/components/schemas/ExportStatus"
        output_location:
          type: string
          description: The location in which the export zip file will be found.
          example: s3://abc/AA/20250213/019587ac-073b-7098-8426-bad970f8c974.csv
          maxLength: 2048
          pattern: '^s3://.+/.+/[0-9]{8}/.+\.csv$'
      description: Payload for export trigger response.
      required:
        - client_id
        - status

    ErrorMessage:
      description: Description of error
      type: object
      properties:
        message:
          type: string
          pattern: "^.+$"
          description: Message describing the cause.
          maxLength: 256
          example: "you must give me good information"
      required:
        - message
      example:
        message: you must include a message