---
openapi: 3.0.3
info:
  title: Query Orchestration API
  description: API documentation for the Query Orchestration services.
  version: 0.0.1
  contact:
    email: piragavarapu@aarete.com
    name: Aarete Inc.
    url: https://aarete.com
  license:
    name: Aarete Inc.internal use
    url: https://aarete.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: FolderService
    description: Operations related to document folders and organization
  - name: LabelService
    description: Operations related to document labels and workflow tracking
  - name: FieldExtractionService
    description: Operations related to document field extractions
  - name: QueryService
    description: Operations related to queries
  - name: ExportService
    description: Operations related to exports
  - name: AuthService
    description: Operations related to authentication
  - name: AdminService
    description: Operations related to user management and administration

paths:

  /client:
    post:
      operationId: createClient
      tags:
        - ClientService
      summary: Create a new client
      description: Creates a new client with the provided details.
      security:
        - jwtAuth: []
      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"

  /clients:
    get:
      operationId: listClients
      tags:
        - ClientService
      summary: List all clients
      description: Returns a list of all clients in the system.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: List of clients retrieved successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientListResponse"
        "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:
        - jwtAuth: []
      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:
        - jwtAuth: []
      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:
        - QueryService
      summary: List queries
      description: Retrieves a list of queries based on filter criteria.
      security:
        - jwtAuth: []
      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:
        - QueryService
      summary: Create a new query
      description: Creates a new query with the provided details.
      security:
        - jwtAuth: []
      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:
        - QueryService
      summary: Get a query by ID
      description: Retrieves a specific query by its ID.
      security:
        - jwtAuth: []
      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:
        - QueryService
      summary: Update a query
      description: Updates an existing query with new details.
      security:
        - jwtAuth: []
      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:
        - QueryService
      summary: Test a query
      description: Executes a test run of a query with the provided parameters.
      security:
        - jwtAuth: []
      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:
        - jwtAuth: []
      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:
        - jwtAuth: []
      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:
        - jwtAuth: []
      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}/folders:
    parameters:
      - $ref: "#/components/parameters/ClientID"
    get:
      operationId: listClientFolders
      tags:
        - FolderService
      summary: List folders for a client
      description: |
        Returns all folders belonging to a client. The response includes each folder's
        ID, path, and parent folder ID, allowing clients to reconstruct the folder hierarchy.
        Root-level folders will have a null parentId.

        When metrics=true is specified, each folder will include processing metrics
        (document counts and label breakdown). This adds overhead so should only be
        used when metrics are needed.
      security:
        - jwtAuth: []
      parameters:
        - name: metrics
          in: query
          required: false
          description: |
            When true, include processing metrics for each folder (document counts by label).
            Defaults to false for performance reasons.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: List of folders for the client.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FolderList"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /client/{id}/document:
    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:
        - jwtAuth: []
      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"
    post:
      operationId: uploadDocument
      tags:
        - DocumentsService
      summary: Upload a file
      description: Upload a single file to the server with optional metadata
      security:
        - jwtAuth: []
      requestBody:
        required: true
        description: upload file body
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  maxLength: 107374182400
                  description: The file to upload
                filename:
                  type: string
                  pattern: ".+"
                  maxLength: 4096
                  description: Optional custom filename
                  example: "document.pdf"
            encoding:
              file:
                contentType: application/pdf
                style: form
                explode: false
      responses:
        "200":
          description: Document uploaded.
          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}/document/batch:
    parameters:
      - $ref: "#/components/parameters/ClientID"
    post:
      operationId: uploadDocumentBatch
      tags:
        - DocumentsService
      summary: Upload multiple PDF documents as ZIP archive
      description: Upload a ZIP archive containing multiple PDF documents for async batch processing
      security:
        - jwtAuth: []
      requestBody:
        required: true
        description: ZIP archive containing PDF documents
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - archive
              properties:
                archive:
                  type: string
                  format: binary
                  maxLength: 1073741824  # 1GB limit for ZIP files
                  description: The file to be uploaded as a ZIP archive
            encoding:
              archive:
                contentType: application/zip
                style: form
                explode: false
      responses:
        "202":
          description: Batch upload accepted for processing
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchUploadResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    get:
      operationId: listDocumentBatches
      tags:
        - DocumentsService
      summary: List batch uploads for a client
      description: Retrieves a list of batch uploads for the specified client
      security:
        - jwtAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
          description: Maximum number of items to return
        - in: query
          name: offset
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 2147483647
            default: 0
          description: Number of items to skip
      responses:
        "200":
          description: List of batch uploads
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchUploadList"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /client/{id}/document/batch/{batch_id}:
    parameters:
      - $ref: "#/components/parameters/ClientID"
      - $ref: "#/components/parameters/BatchID"
    get:
      operationId: getDocumentBatch
      tags:
        - DocumentsService
      summary: Get batch upload status
      description: Retrieves detailed status information for a specific batch upload
      security:
        - jwtAuth: []
      responses:
        "200":
          description: Batch upload details
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BatchUploadDetails"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: cancelDocumentBatch
      tags:
        - DocumentsService
      summary: Cancel a batch upload
      description: Cancels a batch upload that is currently processing
      security:
        - jwtAuth: []
      responses:
        "204":
          description: Batch upload cancelled successfully
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "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, including metadata such as
        folder, filename, labels, and optionally the full text extraction record.
      security:
        - jwtAuth: []
      parameters:
        - name: textRecord
          in: query
          required: false
          description: When true, includes the full text extraction record in the response
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Document details.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentEnriched"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /folders:
    post:
      operationId: createFolder
      tags:
        - FolderService
      summary: Create a new folder
      description: Creates a new folder for organizing documents.
      security:
        - jwtAuth: []
      requestBody:
        description: The details required to create a folder
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FolderCreate"
      responses:
        "201":
          description: Folder created successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Folder"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /folders/{folderId}:
    parameters:
      - name: folderId
        in: path
        required: true
        description: The folder ID
        schema:
          type: string
          format: uuid
          maxLength: 50
    patch:
      operationId: renameFolder
      tags:
        - FolderService
      summary: Rename a folder
      description: Updates the folder path/name.
      security:
        - jwtAuth: []
      requestBody:
        description: The new folder path
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FolderRename"
      responses:
        "200":
          description: Folder renamed successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Folder"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /folders/{folderId}/documents:
    parameters:
      - name: folderId
        in: path
        required: true
        description: The folder ID
        schema:
          type: string
          format: uuid
          maxLength: 50
    get:
      operationId: getFolderDocuments
      tags:
        - FolderService
      summary: Get documents in a folder
      description: |
        Retrieves all documents within a specific folder, including filename and labels.
        Optionally includes the full text extraction record for each document.
        Returns a lighter-weight format than GET /document/{id} (excludes client_id and computed fields).
      security:
        - jwtAuth: []
      parameters:
        - name: textRecord
          in: query
          required: false
          description: When true, includes the full text extraction record for each document
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: List of documents in folder.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    maxItems: 10000
                    items:
                      $ref: "#/components/schemas/DocumentInFolder"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /folders/{folderId}/metrics:
    parameters:
      - name: folderId
        in: path
        required: true
        description: The folder ID
        schema:
          type: string
          format: uuid
          maxLength: 50
    get:
      operationId: getFolderMetrics
      tags:
        - FolderService
      summary: Get folder processing metrics
      description: Retrieves processing progress metrics for documents in a folder.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: Folder metrics.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FolderMetrics"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /documents/{documentId}/labels:
    parameters:
      - name: documentId
        in: path
        required: true
        description: The document ID
        schema:
          type: string
          format: uuid
          maxLength: 50
    post:
      operationId: applyLabel
      tags:
        - LabelService
      summary: Apply a label to a document
      description: Applies a workflow label to a document for tracking processing state.
      security:
        - jwtAuth: []
      requestBody:
        description: The label to apply
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LabelApplication"
      responses:
        "201":
          description: Label applied successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LabelRecord"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    get:
      operationId: getDocumentLabels
      tags:
        - LabelService
      summary: Get all labels for a document
      description: Retrieves all labels that have been applied to a document, ordered by most recent first.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: List of labels.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                type: object
                properties:
                  labels:
                    type: array
                    maxItems: 1000
                    items:
                      $ref: "#/components/schemas/LabelRecord"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /labels/{labelName}/documents:
    parameters:
      - name: labelName
        in: path
        required: true
        description: The label name
        schema:
          type: string
          maxLength: 100
          pattern: "^[A-Za-z0-9_]+$"
      - name: clientId
        in: query
        required: true
        description: The client ID to filter documents
        schema:
          $ref: "#/components/schemas/ClientID"
    get:
      operationId: getDocumentsByLabel
      tags:
        - LabelService
      summary: Get all documents with a specific label
      description: Retrieves all documents that have been tagged with a specific label.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: List of documents with this label.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    maxItems: 10000
                    items:
                      $ref: "#/components/schemas/DocumentSummary"
        "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:
        - jwtAuth: []
      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:
        - jwtAuth: []
      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"

  /field-extractions:
    post:
      operationId: createFieldExtraction
      tags:
        - FieldExtractionService
      summary: Create a new field extraction
      description: Creates a new field extraction with single-value and array fields for a document.
      security:
        - jwtAuth: []
      requestBody:
        description: The field extraction data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FieldExtractionRequest"
      responses:
        "201":
          description: Field extraction created successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldExtractionResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    get:
      operationId: getCurrentFieldExtraction
      tags:
        - FieldExtractionService
      summary: Get current field extraction
      description: Retrieves the most recent field extraction for a document.
      security:
        - jwtAuth: []
      parameters:
        - name: documentId
          in: query
          required: true
          description: The document ID
          schema:
            type: string
            format: uuid
            maxLength: 50
      responses:
        "200":
          description: Current field extraction.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldExtractionResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /field-extractions/version:
    get:
      operationId: getFieldExtractionByVersion
      tags:
        - FieldExtractionService
      summary: Get field extraction by version
      description: Retrieves a specific version of field extraction for a document.
      security:
        - jwtAuth: []
      parameters:
        - name: documentId
          in: query
          required: true
          description: The document ID
          schema:
            type: string
            format: uuid
            maxLength: 50
        - name: version
          in: query
          required: true
          description: The version number to retrieve
          schema:
            type: integer
            format: int64
            minimum: 1
            maximum: 9223372036854775807
      responses:
        "200":
          description: Field extraction for the specified version.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldExtractionResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /field-extractions/history:
    get:
      operationId: getFieldExtractionHistory
      tags:
        - FieldExtractionService
      summary: Get field extraction version history
      description: Retrieves all versions of field extractions for a document, ordered by most recent first.
      security:
        - jwtAuth: []
      parameters:
        - name: documentId
          in: query
          required: true
          description: The document ID
          schema:
            type: string
            format: uuid
            maxLength: 50
      responses:
        "200":
          description: Field extraction history.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    maxItems: 1000
                    items:
                      $ref: "#/components/schemas/FieldExtractionVersion"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /login:
    get:
      operationId: login
      tags:
        - AuthService
      summary: Login to the application
      description: >-
        Initiates the login flow by redirecting to Cognito IDP login page.
      security:
        - {}
        - cognitoAuth: [openid, email, profile]
      responses:
        "302":
          description: Redirect to Cognito login page
          headers:
            Location:
              schema:
                type: string
                format: uri
                maxLength: 2048
                pattern: "^https://.*"
              description: URL to the Cognito login page
            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"

  /login-callback:
    get:
      operationId: loginCallback
      tags:
        - AuthService
      summary: OAuth2 callback endpoint
      description: >-
        Handles the OAuth2 callback during the login process. Receives the
        authorization code from Cognito IDP and exchanges it for tokens.
      security:
        - {}
      parameters:
        - name: code
          in: query
          description: Authorization code from Cognito
          required: true
          schema:
            type: string
            maxLength: 2048
            pattern: "^[A-Za-z0-9\\-_]+$"
        - name: state
          in: query
          description: State parameter for CSRF protection
          required: true
          schema:
            type: string
            maxLength: 1024
            pattern: "^[A-Za-z0-9\\-_]+$"
      responses:
        "302":
          description: Redirect to application after successful login
          headers:
            Location:
              schema:
                type: string
                format: uri
                maxLength: 2048
                pattern: "^https?://.*"
              description: URL to redirect after successful login
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /logout:
    get:
      operationId: logout
      tags:
        - AuthService
      summary: Logout from the application
      description: >-
        Logs the user out by invalidating the session and redirecting to
        Cognito logout endpoint.
      security:
        - jwtAuth: []
      responses:
        "302":
          description: Redirect to Cognito logout page or application home page
          headers:
            Location:
              schema:
                type: string
                format: uri
                maxLength: 2048
                pattern: "^https?://.*"
              description: URL to redirect after logout
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /identity:
    get:
      operationId: getIdentity
      tags:
        - AuthService
      summary: Get current user identity and roles
      description: >-
        Returns the authenticated user's assigned roles from Permit.io,
        including the permissions granted by each role.
        Any authenticated user can call this endpoint to discover their own roles.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: User roles and permissions retrieved successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentityResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          description: Failed to retrieve roles from Permit.io
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorMessage"

  /home:
    get:
      operationId: getHomePage
      tags:
        - AuthService
      summary: Get the home page menu
      description: >-
        Returns the HTML menu page for authenticated users.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: Home page HTML
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            text/html:
              schema:
                type: string
                description: HTML content for the home page menu
                maxLength: 1048576
                pattern: "^.*$"
                format: html
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /admin/users:
    post:
      operationId: createAdminUser
      tags:
        - AdminService
      summary: Create a new user
      description: >-
        Creates a new user in both AWS Cognito and Permit.io systems with optional role assignments.
        Idempotent - returns 200 OK if user already exists with identical attributes.


        **Creation Flow:**

        1. User is created in AWS Cognito (primary authentication system)

        2. If Cognito creation fails, operation fails with HTTP 502 (no user created)

        3. User is created in Permit.io (authorization/role system)

        4. If Permit.io creation fails, user still exists in Cognito but permit_synced=false

        5. Roles are assigned in Permit.io (best-effort, continues on failures)


        **Role Assignment Behavior:**

        - Roles must exist in your Permit.io environment (e.g., super_admin, user_admin, auditor, client_user)

        - Invalid/non-existent roles fail silently and are logged server-side

        - Only successfully assigned roles appear in the roles_assigned response field

        - The roles_assigned array may be a subset of the requested roles array

        - If all roles fail, roles_assigned will be null or empty (user has no permissions)


        **Partial Success Scenarios:**

        - Returns HTTP 201 even if Permit.io creation or some role assignments fail

        - Check permit_synced field: false indicates user was not created in Permit.io

        - Compare roles_assigned vs requested roles to detect role assignment failures

        - User can authenticate (Cognito) but may lack authorization (Permit.io) if sync fails
      security:
        - jwtAuth: []
      requestBody:
        description: The user details required to create a user
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AdminUserCreate"
      responses:
        "201":
          description: User created successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUserCreateResponse"
        "200":
          description: User already exists with matching attributes (idempotent).
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUserCreateResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/BadGateway"
    get:
      operationId: listAdminUsers
      tags:
        - AdminService
      summary: List users
      description: >-
        Lists users from AWS Cognito with pagination, filtering, and sorting support.
      security:
        - jwtAuth: []
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            format: int32
            minimum: 1
            default: 1
            maximum: 10000
        - name: page_size
          in: query
          description: Number of results per page
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 50
        - name: search
          in: query
          description: Search term for email/name filtering
          schema:
            type: string
            maxLength: 256
            pattern: "^.+$"
        - name: status
          in: query
          description: Filter by user status
          schema:
            type: string
            enum: [enabled, disabled, all]
            default: all
        - name: sort_by
          in: query
          description: Field to sort by
          schema:
            type: string
            enum: [email, created_at, last_name]
            default: email
        - name: sort_order
          in: query
          description: Sort direction
          schema:
            type: string
            enum: [asc, desc]
            default: asc
      responses:
        "200":
          description: List of users.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUserList"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /admin/users/{email}:
    parameters:
      - $ref: "#/components/parameters/UserEmail"
    get:
      operationId: getAdminUser
      tags:
        - AdminService
      summary: Get user by email
      description: >-
        Retrieves user details from both AWS Cognito and Permit.io by email address.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: User details.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUserDetails"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    head:
      operationId: checkAdminUserExists
      tags:
        - AdminService
      summary: Check if user exists
      description: >-
        Checks if a user exists in Cognito and/or Permit.io without returning full details.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: User exists.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
            X-User-Exists-Cognito:
              schema:
                type: boolean
              description: Whether user exists in Cognito
            X-User-Exists-PermitIO:
              schema:
                type: boolean
              description: Whether user exists in Permit.io
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: User does not exist in either system
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      operationId: updateAdminUser
      tags:
        - AdminService
      summary: Update user attributes and roles
      description: >-
        Updates user attributes (first_name, last_name) in Cognito and manages role assignments in Permit.io.
        Email address cannot be changed (use email path parameter to identify user).


        **Attribute Updates:**

        - first_name and last_name are updated in AWS Cognito

        - Omit fields you don't want to change (e.g., send only roles to change roles)


        **Role Management (REPLACE Strategy):**

        - Providing a roles array REPLACES all existing roles (not additive)

        - To add a role: include ALL current roles PLUS the new role

        - To remove a role: include only the roles you want to keep

        - To remove all roles: send an empty array []

        - Omitting the roles field leaves role assignments unchanged


        **Role Assignment Behavior:**

        - Roles must exist in your Permit.io environment

        - Invalid/non-existent roles fail silently and are logged server-side

        - Response.roles field shows the final state after successful assignments

        - Compare response.roles vs requested roles to detect failures


        **Example - Add a Role:**

        Current roles: ["client_user"]

        To add "auditor": send roles: ["client_user", "auditor"]

        Result: ["client_user", "auditor"]


        **Example - Replace All Roles:**

        Current roles: ["auditor", "client_user"]

        To change to just "super_admin": send roles: ["super_admin"]

        Result: ["super_admin"] (auditor and client_user removed)
      security:
        - jwtAuth: []
      requestBody:
        description: The user attributes to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AdminUserUpdate"
      responses:
        "200":
          description: User updated successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUserDetails"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: deleteAdminUser
      tags:
        - AdminService
      summary: Delete user permanently
      description: >-
        Permanently deletes a user from both AWS Cognito and Permit.io.
        This operation is irreversible. Requires confirm=true query parameter.
      security:
        - jwtAuth: []
      parameters:
        - name: confirm
          in: query
          description: Must be set to true to confirm deletion
          required: true
          schema:
            type: boolean
      responses:
        "200":
          description: User deleted successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUserDeleteResponse"
        "207":
          description: User partially deleted (multi-status).
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUserDeleteResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /admin/users/{email}/disable:
    parameters:
      - $ref: "#/components/parameters/UserEmail"
    post:
      operationId: disableAdminUser
      tags:
        - AdminService
      summary: Disable user
      description: >-
        Disables a user in AWS Cognito, preventing authentication.
        User data and roles are preserved. Idempotent.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: User disabled successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUserActionResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"

  /admin/users/{email}/enable:
    parameters:
      - $ref: "#/components/parameters/UserEmail"
    post:
      operationId: enableAdminUser
      tags:
        - AdminService
      summary: Enable user
      description: >-
        Re-enables a previously disabled user in AWS Cognito.
        Restores authentication capability. Idempotent.
      security:
        - jwtAuth: []
      responses:
        "200":
          description: User enabled successfully.
          headers:
            RateLimit:
              $ref: "#/components/headers/RateLimit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminUserActionResponse"
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "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.

    BatchID:
      in: path
      name: batch_id
      required: true
      schema:
        $ref: "#/components/schemas/BatchID"
      description: The batch upload ID.

    UserEmail:
      in: path
      name: email
      required: true
      schema:
        type: string
        format: email
        maxLength: 320
      description: URL-encoded user email address.

  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:
    jwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT token obtained after Cognito authentication. Implements RFC8725 JWT
        best practices for security.
    cognitoAuth:
      type: oauth2
      description: >-
        Authentication using Amazon Cognito IDP. Implements RFC8725 JWT best
        practices for security.
      flows:
        authorizationCode:
          authorizationUrl: >-
            https://doczy.auth.us-east-1.amazoncognito.com/oauth2/authorize
          tokenUrl: >-
            https://doczy.auth.us-east-1.amazoncognito.com/oauth2/token
          scopes:
            openid: Get OIDC token
            email: Access to user's email
            profile: Access to user's profile

  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"

    NotFound:
      description: Resource not found.
      headers:
        RateLimit:
          $ref: "#/components/headers/RateLimit"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

    Forbidden:
      description: Insufficient permissions to perform this action.
      headers:
        RateLimit:
          $ref: "#/components/headers/RateLimit"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

    Conflict:
      description: Resource already exists or state conflict.
      headers:
        RateLimit:
          $ref: "#/components/headers/RateLimit"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

    BadGateway:
      description: External service error.
      headers:
        RateLimit:
          $ref: "#/components/headers/RateLimit"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorMessage"

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

    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

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

    BatchStatus:
      type: string
      enum:
        - processing
        - completed
        - failed
        - cancelled
      description: The status of a batch upload

    BatchUploadResponse:
      type: object
      description: Response returned when a batch upload is accepted for processing
      required:
        - batch_id
        - status
        - status_url
      properties:
        batch_id:
          $ref: "#/components/schemas/BatchID"
        status:
          $ref: "#/components/schemas/BatchStatus"
        status_url:
          type: string
          format: uri-reference
          maxLength: 512
          description: URL to check batch status
          example: "/client/AAA/document/batch/019580df-ef65-7676-8de9-94435a93337a"

    BatchUploadSummary:
      type: object
      description: Summary information about a batch upload
      required:
        - batch_id
        - client_id
        - original_filename
        - status
        - total_documents
        - processed_documents
        - failed_documents
        - invalid_type_documents
        - progress_percent
        - created_at
      properties:
        batch_id:
          $ref: "#/components/schemas/BatchID"
        client_id:
          $ref: "#/components/schemas/ClientID"
        original_filename:
          type: string
          maxLength: 4096
          pattern: "^.+$"
          description: Original filename of the uploaded ZIP archive
          example: "documents.zip"
        status:
          $ref: "#/components/schemas/BatchStatus"
        total_documents:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Total number of documents in the batch
          example: 100
        processed_documents:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Number of documents processed so far
          example: 42
        failed_documents:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Number of documents that failed processing
          example: 2
        invalid_type_documents:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Number of non-PDF files found in archive
          example: 1
        progress_percent:
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          description: Processing progress percentage
          example: 42
        created_at:
          type: string
          format: date-time
          maxLength: 50
          description: When the batch upload was created
        completed_at:
          type: string
          format: date-time
          maxLength: 50
          nullable: true
          description: When the batch upload completed processing

    BatchUploadDetails:
      description: Detailed information about a batch upload including failed filenames
      allOf:
        - $ref: "#/components/schemas/BatchUploadSummary"
        - type: object
          properties:
            failed_filenames:
              type: array
              maxItems: 10000
              items:
                type: string
                maxLength: 4096
                pattern: "^.+$"
              description: List of filenames that failed processing
              example: ["doc3.pdf", "doc17.pdf"]

    BatchUploadList:
      type: object
      description: List of batch uploads for a client
      required:
        - batches
        - total_count
      properties:
        batches:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/BatchUploadSummary"
        total_count:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Total number of batches for this client
          example: 25

    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:
        id:
          $ref: "#/components/schemas/ClientID"
        name:
          $ref: "#/components/schemas/ClientName"
        can_sync:
          $ref: "#/components/schemas/ClientCanSync"
      required:
        - id
        - 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

    ClientListResponse:
      description: Response containing a list of all clients.
      type: object
      properties:
        clients:
          type: array
          description: List of clients in the system.
          maxItems: 10000
          items:
            $ref: "#/components/schemas/DocClient"
        totalCount:
          type: integer
          format: int32
          description: Total number of clients.
          minimum: 0
          maximum: 2147483647
      required:
        - clients
        - totalCount

    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

    DocumentEnriched:
      description: Enriched document details with additional metadata
      type: object
      required:
        - id
        - client_id
        - hash
        - fields
        - hasTextRecord
        - labels
      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
        hasTextRecord:
          type: boolean
          description: "Whether a text extraction (field extraction) record exists for this document"
        folderId:
          type: string
          format: uuid
          maxLength: 50
          description: "Parent folder ID, null if document is not in a folder"
        filename:
          type: string
          maxLength: 4096
          description: "Original filename of the document"
        originalPath:
          type: string
          maxLength: 4096
          description: "Original path provided during upload (immutable)"
        labels:
          type: array
          maxItems: 1000
          items:
            $ref: "#/components/schemas/LabelRecord"
          description: "All labels applied to this document"
        textRecord:
          $ref: "#/components/schemas/FieldExtractionResponse"

    DocumentInFolder:
      description: Document within a folder with enriched metadata (lighter format, excludes client_id and fields)
      type: object
      required:
        - id
        - hash
        - hasTextRecord
        - labels
      properties:
        id:
          $ref: "#/components/schemas/DocumentID"
        hash:
          $ref: "#/components/schemas/Hash"
        hasTextRecord:
          type: boolean
          description: "Whether a text extraction record exists for this document"
        folderId:
          type: string
          format: uuid
          maxLength: 50
          description: "Parent folder ID"
        filename:
          type: string
          maxLength: 4096
          description: "Original filename of the document"
        originalPath:
          type: string
          maxLength: 4096
          description: "Original path provided during upload (immutable)"
        labels:
          type: array
          maxItems: 1000
          items:
            $ref: "#/components/schemas/LabelRecord"
          description: "All labels applied to this document"
        textRecord:
          $ref: "#/components/schemas/FieldExtractionResponse"

    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://a/A/export/20250213/uuid.csv
          maxLength: 2048
          pattern: '^s3://.+/.+/export/[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

    # Identity API schemas
    IdentityRole:
      type: object
      description: A role assigned to the user with its permissions
      required:
        - key
        - name
        - permissions
      properties:
        key:
          type: string
          description: The role key/identifier
          maxLength: 128
          pattern: "^[a-z0-9_-]+$"
          example: "auditor"
        name:
          type: string
          description: Human-readable role name
          maxLength: 256
          pattern: "^.+$"
          example: "Auditor"
        description:
          type: string
          description: Optional description of the role
          maxLength: 1024
          example: "Read-only access to view documents and exports"
        permissions:
          type: array
          description: List of permissions granted by this role
          maxItems: 500
          items:
            type: string
            maxLength: 128
            pattern: "^[a-z0-9_-]+:[a-z0-9_-]+$"
          example: ["document:read", "document:list", "export:read"]

    IdentityResponse:
      type: object
      description: Response containing the user's roles and their permissions
      required:
        - roles
      properties:
        roles:
          type: array
          description: List of roles assigned to the user with their permissions
          maxItems: 100
          items:
            $ref: "#/components/schemas/IdentityRole"

    # Admin API schemas
    AdminUserCreate:
      description: Request body for creating a new user with email, name, and role assignments
      type: object
      required:
        - email
        - first_name
        - last_name
        - roles
      properties:
        email:
          type: string
          format: email
          maxLength: 320
          pattern: '^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$'
          description: User email address (used as Cognito username)
          example: john.doe@example.com
        first_name:
          type: string
          minLength: 1
          maxLength: 100
          pattern: "^.+$"
          description: User's given name for account creation
          example: John
        last_name:
          type: string
          minLength: 1
          maxLength: 100
          pattern: "^.+$"
          description: User's family name for account creation
          example: Doe
        roles:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            pattern: "^.+$"
            maxLength: 100
          description: >-
            List of role keys to assign in Permit.io (e.g., super_admin, user_admin, auditor, client_user).
            Roles must exist in your Permit.io environment. Invalid roles fail silently - check roles_assigned in response.
          example: ["user_admin", "auditor"]

    AdminUserCreateResponse:
      description: Response after creating a user, including Cognito subject ID and sync status
      type: object
      required:
        - cognito_subject_id
        - email
        - status
        - permit_synced
      properties:
        cognito_subject_id:
          type: string
          maxLength: 256
          pattern: "^.+$"
          description: Created user's Cognito unique subject identifier
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        email:
          type: string
          format: email
          maxLength: 320
          description: User email address
          example: john.doe@example.com
        first_name:
          type: string
          maxLength: 100
          pattern: "^.+$"
          description: Created user's given name
          example: John
        last_name:
          type: string
          maxLength: 100
          pattern: "^.+$"
          description: Created user's family name
          example: Doe
        status:
          type: string
          maxLength: 50
          pattern: "^.+$"
          description: Cognito user status
          example: FORCE_CHANGE_PASSWORD
        enabled:
          type: boolean
          description: Whether the created user is enabled in Cognito
          example: true
        permit_synced:
          type: boolean
          description: >-
            Whether user was successfully created in Permit.io authorization system.
            If false, user exists in Cognito (can authenticate) but not in Permit.io (has no authorization/permissions).
            Manual sync or retry may be required.
          example: true
        roles_assigned:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 100
            pattern: "^.+$"
          description: >-
            Roles that were successfully assigned in Permit.io. May be a subset of requested roles if some failed.
            Compare with requested roles array to detect assignment failures. If null or empty, no roles were assigned
            (user has no permissions). Only present if permit_synced is true.
          example: ["user_admin", "auditor"]
        created_at:
          type: string
          format: date-time
          maxLength: 50
          description: Timestamp when the user was created in the system
          example: "2025-10-16T14:23:45Z"

    AdminUserDetails:
      description: Complete user information from Cognito and Permit.io including roles and timestamps
      type: object
      required:
        - cognito_subject_id
        - email
        - status
        - enabled
      properties:
        cognito_subject_id:
          type: string
          maxLength: 256
          pattern: "^.+$"
          description: User's Cognito unique subject identifier from authentication system
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        email:
          type: string
          format: email
          maxLength: 320
          description: Email address of the user account
          example: john.doe@example.com
        first_name:
          type: string
          maxLength: 100
          pattern: "^.+$"
          description: User's given name retrieved from Cognito
          example: John
        last_name:
          type: string
          maxLength: 100
          pattern: "^.+$"
          description: User's family name retrieved from Cognito
          example: Doe
        status:
          type: string
          maxLength: 50
          pattern: "^.+$"
          description: Current Cognito user account status
          example: CONFIRMED
        enabled:
          type: boolean
          description: Current enabled status of the user in Cognito
          example: true
        roles:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 100
            pattern: "^.+$"
          description: Roles assigned in Permit.io
          example: ["admin", "viewer"]
        created_at:
          type: string
          format: date-time
          maxLength: 50
          description: Timestamp when the user account was created
          example: "2025-10-15T09:15:30Z"
        updated_at:
          type: string
          format: date-time
          maxLength: 50
          description: Timestamp of last update
          example: "2025-10-16T14:20:10Z"

    AdminUserUpdate:
      description: Request body for updating user attributes (first name, last name, and roles)
      type: object
      properties:
        first_name:
          type: string
          minLength: 1
          maxLength: 100
          pattern: "^.+$"
          description: Updated given name for the user
          example: Jonathan
        last_name:
          type: string
          minLength: 1
          maxLength: 100
          pattern: "^.+$"
          description: Updated family name for the user
          example: Doe-Smith
        roles:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            pattern: "^.+$"
            maxLength: 100
          description: >-
            Complete list of role keys to assign in Permit.io - REPLACES all existing roles (not additive).
            To add a role, include all current roles plus the new one. To remove a role, omit it from the array.
            Roles must exist in Permit.io environment. Invalid roles fail silently - check response.roles for final state.
            Omit this field entirely to leave roles unchanged.
          example: ["user_admin", "auditor"]

    AdminUserList:
      description: Paginated list of users with total count and pagination metadata
      type: object
      required:
        - users
        - total
        - page
        - page_size
      properties:
        users:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/AdminUserDetails'
          description: List of users for current page
        total:
          type: integer
          format: int32
          minimum: 0
          maximum: 2147483647
          description: Total number of users matching filter
          example: 147
        page:
          type: integer
          format: int32
          minimum: 1
          maximum: 10000
          description: Current page number
          example: 1
        page_size:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          description: Number of users per page
          example: 20
        has_more:
          type: boolean
          description: Whether more pages are available
          example: true

    AdminUserActionResponse:
      description: Response for user enable/disable actions with success status and timestamp
      type: object
      required:
        - success
        - email
        - action
      properties:
        success:
          type: boolean
          description: Whether the action succeeded
          example: true
        email:
          type: string
          format: email
          maxLength: 320
          description: Email of the user acted upon
          example: john.doe@example.com
        action:
          type: string
          enum: [disable, enable]
          description: Action performed
          example: disable
        cognito_subject_id:
          type: string
          maxLength: 256
          pattern: "^.+$"
          description: Cognito subject identifier for the action response
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        timestamp:
          type: string
          format: date-time
          maxLength: 50
          description: Timestamp of the action
          example: "2025-10-16T14:25:33Z"

    AdminUserDeleteResponse:
      description: Response for user deletion with status from each system (Cognito and Permit.io)
      type: object
      required:
        - success
        - email
        - deleted_from
      properties:
        success:
          type: boolean
          description: Whether the deletion succeeded
          example: true
        email:
          type: string
          format: email
          maxLength: 320
          description: Email of the deleted user
          example: john.doe@example.com
        cognito_subject_id:
          type: string
          maxLength: 256
          pattern: "^.+$"
          description: Cognito subject identifier of the deleted user
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        deleted_from:
          type: object
          required:
            - cognito
            - permit
          properties:
            cognito:
              type: boolean
              description: Whether user was deleted from Cognito
              example: true
            permit:
              type: boolean
              description: Whether user was deleted from Permit.io
              example: true
          description: Deletion status from each system
        timestamp:
          type: string
          format: date-time
          maxLength: 50
          description: Timestamp of the deletion
          example: "2025-10-16T14:27:15Z"

    # Folder schemas
    FolderCreate:
      description: Request to create a new folder for organizing documents
      type: object
      required:
        - path
        - clientId
        - createdBy
      properties:
        path:
          type: string
          maxLength: 1000
          pattern: "^/.*$"
          description: Folder path (must start with /). Use "/" for root folder.
          example: "/documents/2024"
        parentId:
          type: string
          format: uuid
          maxLength: 50
          description: Optional parent folder ID
          example: "019580df-ef65-7676-8de9-94435a93337a"
        clientId:
          $ref: "#/components/schemas/ClientID"
        createdBy:
          type: string
          format: email
          maxLength: 320
          description: Email of user who created the folder
          example: user@example.com

    FolderRename:
      description: Request to rename an existing folder
      type: object
      required:
        - path
      properties:
        path:
          type: string
          maxLength: 1000
          pattern: "^/.*$"
          description: New folder path (must start with /). Use "/" for root folder.
          example: "/documents/2024-renamed"

    Folder:
      description: Folder information for organizing documents
      type: object
      required:
        - id
        - path
        - clientId
        - createdAt
        - createdBy
      properties:
        id:
          type: string
          format: uuid
          maxLength: 50
          description: Folder ID
          example: "019580df-ef65-7676-8de9-94435a93337a"
        path:
          type: string
          maxLength: 1000
          pattern: "^/.*$"
          description: Folder path (must start with /). Root folder has path "/".
          example: "/documents/2024"
        parentId:
          type: string
          format: uuid
          maxLength: 50
          nullable: true
          description: Parent folder ID
          example: "019580df-ef65-7676-8de9-94435a93337b"
        clientId:
          $ref: "#/components/schemas/ClientID"
        createdAt:
          type: string
          format: date-time
          maxLength: 50
          description: Creation timestamp
          example: "2025-10-16T14:27:15Z"
        createdBy:
          type: string
          format: email
          maxLength: 320
          description: Email of the user who created this folder
          example: user@example.com
        metrics:
          allOf:
            - $ref: "#/components/schemas/FolderMetricsInline"
          nullable: true
          description: |
            Processing metrics for this folder. Only populated when metrics=true
            is specified in the request. Null otherwise.

    FolderList:
      description: List of folders for a client
      type: object
      required:
        - folders
      properties:
        folders:
          type: array
          maxItems: 10000
          description: |
            List of folders. Each folder includes its ID, path, and parentId.
            Root-level folders have parentId set to null. Clients can use
            parentId to reconstruct the folder hierarchy/tree structure.
          items:
            $ref: "#/components/schemas/Folder"

    FolderMetrics:
      description: Processing metrics for a folder including document counts
      type: object
      required:
        - folderId
        - totalDocuments
        - byLabel
      properties:
        folderId:
          type: string
          format: uuid
          maxLength: 50
          description: Unique identifier for the folder
          example: "019580df-ef65-7676-8de9-94435a93337a"
        totalDocuments:
          type: integer
          format: int32
          minimum: 0
          maximum: 1000000
          description: Total number of documents in folder
          example: 150
        byLabel:
          type: object
          maxProperties: 100
          additionalProperties:
            type: integer
            format: int32
            minimum: 0
            maximum: 1000000
          description: Document counts by label
          example:
            Ingested: 150
            OCR_Processed: 120
            Dashboard_Ready: 100

    FolderMetricsInline:
      description: Inline processing metrics for a folder (excludes folderId since it's on parent)
      type: object
      required:
        - totalDocuments
        - byLabel
      properties:
        totalDocuments:
          type: integer
          format: int32
          minimum: 0
          maximum: 1000000
          description: Total number of documents in folder
          example: 150
        byLabel:
          type: object
          maxProperties: 100
          additionalProperties:
            type: integer
            format: int32
            minimum: 0
            maximum: 1000000
          description: Document counts by label
          example:
            Ingested: 150
            OCR_Processed: 120
            Dashboard_Ready: 100

    # Label schemas
    LabelApplication:
      description: Request to apply a workflow label to a document
      type: object
      required:
        - label
        - appliedBy
      properties:
        label:
          type: string
          maxLength: 100
          pattern: "^[A-Za-z0-9_]+$"
          description: Label name (alphanumeric and underscore only)
          example: "OCR_Processed"
        appliedBy:
          type: string
          format: email
          maxLength: 320
          description: Email of user applying the label
          example: user@example.com

    LabelRecord:
      description: Record of a label applied to a document
      type: object
      required:
        - id
        - documentId
        - label
        - appliedBy
        - appliedAt
      properties:
        id:
          type: string
          format: uuid
          maxLength: 50
          description: Label record ID
          example: "019580df-ef65-7676-8de9-94435a93337a"
        documentId:
          $ref: "#/components/schemas/DocumentID"
        label:
          type: string
          maxLength: 100
          pattern: "^[A-Za-z0-9_]+$"
          description: Workflow label name (alphanumeric and underscore only)
          example: "OCR_Processed"
        appliedBy:
          type: string
          format: email
          maxLength: 320
          description: Email of the user who applied this label
          example: user@example.com
        appliedAt:
          type: string
          format: date-time
          maxLength: 50
          description: Timestamp when label was applied
          example: "2025-10-16T14:27:15Z"

    # Field Extraction schemas
    FieldExtractionRequest:
      description: Request to create a new field extraction with single and array fields
      type: object
      required:
        - documentId
        - singleFields
        - arrayFields
        - createdBy
      properties:
        documentId:
          $ref: "#/components/schemas/DocumentID"
        singleFields:
          $ref: "#/components/schemas/SingleFields"
        arrayFields:
          type: array
          maxItems: 10000
          items:
            $ref: "#/components/schemas/ArrayFieldItem"
          description: Array of field extraction items (all must have consistent structure)
        createdBy:
          type: string
          format: email
          maxLength: 320
          description: Email of user creating the extraction
          example: user@example.com

    SingleFields:
      description: Single-value fields for a document extraction (1:1 relationship)
      type: object
      properties:
        fileName:
          type: string
          maxLength: 500
          description: Original file name
          example: "contract_2024.pdf"
        contractTitle:
          type: string
          maxLength: 500
          description: Title of the contract
        aareteDerivedAmendmentNum:
          type: integer
          format: int32
          minimum: 0
          maximum: 999
          description: Amendment number derived by Aarete
        clientName:
          type: string
          maxLength: 500
          description: Name of the client
        payerName:
          type: string
          maxLength: 500
          description: Name of the payer
        payerState:
          type: string
          maxLength: 2
          pattern: "^[A-Z]{2}$"
          description: Two-letter state code for payer
          example: "CA"
        providerState:
          type: string
          maxLength: 2
          pattern: "^[A-Z]{2}$"
          description: Two-letter state code for provider
          example: "NY"
        filenameTin:
          type: string
          maxLength: 20
          description: Tax Identification Number from filename
        provGroupTin:
          type: string
          maxLength: 20
          description: Provider group TIN
        provGroupNpi:
          type: string
          maxLength: 20
          description: Provider group NPI
        provGroupNameFull:
          type: string
          maxLength: 500
          description: Full name of provider group
        provOtherTin:
          type: string
          maxLength: 20
          description: Other provider TIN
        provOtherNpi:
          type: string
          maxLength: 20
          description: Other provider NPI
        provOtherNameFull:
          type: string
          maxLength: 500
          description: Full name of other provider
        aareteDerivedEffectiveDt:
          type: string
          format: date
          maxLength: 50
          description: Contract effective date
          example: "2024-01-01"
        aareteDerivedTerminationDt:
          type: string
          format: date
          maxLength: 50
          description: Contract termination date
          example: "2025-12-31"
        autoRenewalInd:
          type: boolean
          description: Auto-renewal indicator
        autoRenewalTerm:
          type: string
          maxLength: 200
          description: Auto-renewal terms

    ArrayFieldItem:
      description: Single row of array field data (112 fields forming one row)
      type: object
      properties:
        exhibitTitle:
          type: string
          maxLength: 500
        exhibitPage:
          type: string
          maxLength: 100
        reimbProvTin:
          type: string
          maxLength: 20
        reimbProvNpi:
          type: string
          maxLength: 20
        reimbProvName:
          type: string
          maxLength: 500
        reimbEffectiveDt:
          type: string
          format: date
          maxLength: 50
        reimbTerminationDt:
          type: string
          format: date
          maxLength: 50
        aareteDerivedClaimTypeCd:
          type: string
          maxLength: 100
        aareteDerivedProduct:
          type: string
          maxLength: 200
        aareteDerivedLob:
          type: string
          maxLength: 200
        aareteDerivedProgram:
          type: string
          maxLength: 200
        aareteDerivedNetwork:
          type: string
          maxLength: 200
        aareteDerivedProvType:
          type: string
          maxLength: 200
        provTaxonomyCd:
          type: string
          maxLength: 100
        provTaxonomyCdDesc:
          type: string
          maxLength: 500
        provSpecialtyCd:
          type: string
          maxLength: 100
        provSpecialtyCdDesc:
          type: string
          maxLength: 500
        placeOfServiceCd:
          type: string
          maxLength: 100
        placeOfServiceCdDesc:
          type: string
          maxLength: 500
        billTypeCd:
          type: string
          maxLength: 100
        billTypeCdDesc:
          type: string
          maxLength: 500
        patientAgeMin:
          type: string
          maxLength: 50
        patientAgeMax:
          type: string
          maxLength: 50
        reimbTerm:
          type: string
          maxLength: 500
        lobProgramRelationship:
          type: string
          maxLength: 200
        lobProductRelationship:
          type: string
          maxLength: 200
        carveoutInd:
          type: boolean
        carveoutCd:
          type: string
          maxLength: 100
        lesserOfInd:
          type: boolean
        greaterOfInd:
          type: boolean
        aareteDerivedReimbMethod:
          type: string
          maxLength: 200
        unitOfMeasure:
          type: string
          maxLength: 100
        reimbPctRate:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        reimbFeeRate:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        reimbConversionFactor:
          type: number
          format: double
          minimum: 0
          maximum: 99999999.9999
        triggerCapThresholdAmt:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        triggerBaseThreshold:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        defaultInd:
          type: boolean
        additionDesc:
          type: string
          maxLength: 1000
        additionMaxFeeRateInc:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        additionMaxPctRateInc:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        aareteDerivedAdditionRateChangeTimeline:
          type: string
          maxLength: 200
        aareteDerivedFeeSchedule:
          type: string
          maxLength: 200
        aareteDerivedFeeScheduleVersion:
          type: string
          maxLength: 100
        serviceTerm:
          type: string
          maxLength: 500
        cpt4ProcCd:
          type: string
          maxLength: 100
        cpt4ProcCdDesc:
          type: string
          maxLength: 500
        cpt4ProcMod:
          type: string
          maxLength: 100
        cpt4ProcModDesc:
          type: string
          maxLength: 500
        revenueCd:
          type: string
          maxLength: 100
        revenueCdDesc:
          type: string
          maxLength: 500
        diagCd:
          type: string
          maxLength: 100
        diagCdDesc:
          type: string
          maxLength: 500
        ndcCd:
          type: string
          maxLength: 100
        ndcCdDesc:
          type: string
          maxLength: 500
        claimAdmitTypeCd:
          type: string
          maxLength: 100
        authAdmitTypeDesc:
          type: string
          maxLength: 500
        claimStatusCd:
          type: string
          maxLength: 100
        claimStatusCdDesc:
          type: string
          maxLength: 500
        grouperType:
          type: string
          maxLength: 100
        grouperCd:
          type: string
          maxLength: 100
        grouperCdDesc:
          type: string
          maxLength: 500
        grouperPctRate:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        grouperBaseRate:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        # Grouper Extended Fields
        aareteDerivedGrouperVersion:
          type: string
          maxLength: 200
        grouperAlternativeLevelOfCare:
          type: string
          maxLength: 200
        grouperSeverityInd:
          type: boolean
        grouperSeverity:
          type: string
          maxLength: 100
        grouperRiskOfMortalitySubclass:
          type: string
          maxLength: 100
        grouperTransferInd:
          type: boolean
        grouperReadmissionsInd:
          type: boolean
        grouperHacInd:
          type: boolean
        # Outlier Fields
        outlierTerm:
          type: string
          maxLength: 500
        outlierFirstDollarInd:
          type: boolean
        rangeNbrDays:
          type: string
          maxLength: 100
        outlierFixedLossNbrDaysThreshold:
          type: number
          format: double
          minimum: 0
          maximum: 99999999.99
        outlierFixedLossThreshold:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        outlierMaximum:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        outlierMaximumFrequency:
          type: number
          format: double
          minimum: 0
          maximum: 99999999.99
        outlierPctRate:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        outlierExclusionCd:
          type: string
          maxLength: 100
        outlierExclusionCdDesc:
          type: string
          maxLength: 500
        # Facility Adjustment Fields
        facilityAdjustmentTerm:
          type: string
          maxLength: 500
        dshInd:
          type: boolean
        dshPctRate:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        dshFeeRate:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        imeInd:
          type: boolean
        imePctRate:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        imeFeeRate:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        ntapInd:
          type: boolean
        ntapPctRate:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        ntapFeeRate:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        ucInd:
          type: boolean
        ucPctRate:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        ucFeeRate:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        gmeInd:
          type: boolean
        gmePctRate:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        gmeFeeRate:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        # Rate Escalator Fields
        rateEscalatorInd:
          type: boolean
        rateEscalatorDesc:
          type: string
          maxLength: 500
        rateEscalatorMaxRateIncPct:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        rateEscalatorRateChangeTimeline:
          type: number
          format: double
          minimum: 0
          maximum: 99999999.99
        # Stop Loss Fields
        stopLossTerm:
          type: string
          maxLength: 500
        stopLossFirstDollarInd:
          type: boolean
        stopLossRangeNbrDays:
          type: number
          format: double
          minimum: 0
          maximum: 99999999.99
        stopLossFixedLossThreshold:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        stopLossMaximum:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        stopLossMaximumFrequency:
          type: number
          format: double
          minimum: 0
          maximum: 99999999.99
        stopLossDailyMaxRate:
          type: number
          format: double
          minimum: 0
          maximum: 9999999999.99
        stopLossPctRateOnExcessCharges:
          type: number
          format: double
          minimum: 0
          maximum: 999.9999
        stopLossExclusionCd:
          type: string
          maxLength: 100
        stopLossExclusionDesc:
          type: string
          maxLength: 500

    FieldExtractionResponse:
      description: Field extraction with version information
      type: object
      required:
        - id
        - documentId
        - version
        - singleFields
        - arrayFields
        - createdAt
        - createdBy
      properties:
        id:
          type: string
          format: uuid
          maxLength: 50
          description: Field extraction ID
          example: "019580df-ef65-7676-8de9-94435a93337a"
        documentId:
          $ref: "#/components/schemas/DocumentID"
        version:
          type: integer
          format: int32
          minimum: 1
          maximum: 9999
          description: Version number (1-based)
          example: 1
        singleFields:
          $ref: "#/components/schemas/SingleFields"
        arrayFields:
          type: array
          maxItems: 10000
          items:
            $ref: "#/components/schemas/ArrayFieldItem"
          description: Array of field extraction items
        createdAt:
          type: string
          format: date-time
          maxLength: 50
          description: Creation timestamp
          example: "2025-10-16T14:27:15Z"
        createdBy:
          type: string
          format: email
          maxLength: 320
          description: Email of user who created this extraction
          example: user@example.com

    FieldExtractionVersion:
      description: Field extraction version summary for history
      type: object
      required:
        - id
        - documentId
        - version
        - createdAt
        - createdBy
      properties:
        id:
          type: string
          format: uuid
          maxLength: 50
          description: Field extraction ID
          example: "019580df-ef65-7676-8de9-94435a93337a"
        documentId:
          $ref: "#/components/schemas/DocumentID"
        version:
          type: integer
          format: int32
          minimum: 1
          maximum: 9999
          description: Version number (1-based)
          example: 1
        createdAt:
          type: string
          format: date-time
          maxLength: 50
          description: Creation timestamp
          example: "2025-10-16T14:27:15Z"
        createdBy:
          type: string
          format: email
          maxLength: 320
          description: Email of user who created this version
          example: user@example.com