openapi: 3.1.0
info:
  title: Matcher APIs
  description: >-
    Complete API reference for the Matcher reconciliation engine, providing
    automated transaction matching between Midaz Ledger and external systems.
  version: 4.3.0
  license:
    name: Elastic License 2.0
    url: https://www.elastic.co/licensing/elastic-license
servers:
  - url: https://matcher.sandbox.lerian.net
paths:
  /v1/contexts:
    get:
      description: |
        Use this endpoint to retrieve all reconciliation contexts.  

        Supports filtering by type and status and uses cursor-based pagination.
      operationId: listContexts
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: Filter by context type
          in: query
          name: type
          schema:
            type: string
            enum:
              - '1:1'
              - 1:N
              - N:M
        - description: Filter by context status
          in: query
          name: status
          schema:
            type: string
            enum:
              - DRAFT
              - ACTIVE
              - PAUSED
              - ARCHIVED
      responses:
        '200':
          description: List of contexts with cursor pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListContextsResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0101:
                  $ref: '#/components/examples/ErrorM0101'
                ErrorM0102:
                  $ref: '#/components/examples/ErrorM0102'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: List reconciliation contexts
      tags:
        - Configuration Contexts
    post:
      description: >-
        Use this endpoint to create a new reconciliation context. Contexts are
        used to scope matching rules and organize your reconciliation
        configuration.
      operationId: createContext
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContextRequest'
        description: Context creation payload
        required: true
      responses:
        '201':
          description: >-
            Successfully created context.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationContextResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Create a reconciliation context
      tags:
        - Configuration Contexts
  /v1/contexts/{contextId}:
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific reconciliation
        context by its identifier.
      operationId: getContext
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationContextResponse'
        '400':
          description: Invalid context ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Get a reconciliation context
      tags:
        - Configuration Contexts
    patch:
      description: >-
        Use this endpoint to update the fields of a specific reconciliation
        context by its identifier.
      operationId: updateContext
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContextRequest'
        description: Context updates
        required: true
      responses:
        '200':
          description: >-
            Successfully updated context.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationContextResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Update a reconciliation context
      tags:
        - Configuration Contexts
  /v1/contexts/{contextId}/clone:
    post:
      description: >-
        Use this endpoint to clone an existing reconciliation context with its
        associated sources, rules, and fee schedules. You can selectively
        include or exclude specific components.
      operationId: cloneContext
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
        - description: The unique identifier of the reconciliation context to clone.
          in: path
          name: contextId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloneContextRequest'
        description: Clone context payload
        required: true
      responses:
        '201':
          description: >-
            Successfully cloned context.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloneContextResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Clone a reconciliation context
      tags:
        - Configuration Contexts
  /v1/contexts/{contextId}/rules:
    get:
      description: >-
        Use this endpoint to retrieve all match rules under a specific context.
        You can filter the results by rule type. The response uses cursor-based
        pagination.
      operationId: listMatchRules
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: Filter by rule type
          in: query
          name: type
          schema:
            type: string
            enum:
              - EXACT
              - TOLERANCE
              - DATE_LAG
      responses:
        '200':
          description: List of match rules with cursor pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMatchRulesResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: List match rules
      tags:
        - Configuration Match Rules
    post:
      description: >-
        Use this endpoint to create a new match rule within a specific context.
        Match rules define how transactions are matched during reconciliation.
      operationId: createMatchRule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMatchRuleRequest'
        description: Match rule creation payload
        required: true
      responses:
        '201':
          description: >-
            Successfully created match rule.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchRuleResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Priority conflict or idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Create a match rule
      tags:
        - Configuration Match Rules
  /v1/contexts/{contextId}/rules/{ruleId}:
    delete:
      description: Use this endpoint to delete a specific match rule by its identifier.
      operationId: deleteMatchRule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the match rule.
          in: path
          name: ruleId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Match rule successfully deleted
        '400':
          description: Invalid rule ID
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '404':
          description: Match rule not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0208:
                  $ref: '#/components/examples/ErrorM0208'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Delete a match rule
      tags:
        - Configuration Match Rules
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific match rule by
        its identifier.
      operationId: getMatchRule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the match rule.
          in: path
          name: ruleId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved match rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchRuleResponse'
        '400':
          description: Invalid rule ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Match rule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Get a match rule
      tags:
        - Configuration Match Rules
    patch:
      description: >-
        Use this endpoint to update the fields of a specific match rule by its
        identifier.
      operationId: updateMatchRule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the match rule.
          in: path
          name: ruleId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMatchRuleRequest'
        description: Match rule updates
        required: true
      responses:
        '200':
          description: >-
            Successfully updated match rule.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchRuleResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Match rule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Priority conflict or idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Update a match rule
      tags:
        - Configuration Match Rules
  /v1/contexts/{contextId}/rules/reorder:
    post:
      description: >-
        Use this endpoint to reorder the priority of match rules within a
        specific context. The order determines which rules are evaluated first
        during reconciliation.
      operationId: reorderMatchRules
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReorderRequest'
        description: Ordered list of rule IDs
        required: true
      responses:
        '204':
          description: >-
            Match rules reordered.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid reorder payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Reorder match rules
      tags:
        - Configuration Match Rules
  /v1/contexts/{contextId}/sources:
    get:
      description: >-
        Use this endpoint to retrieve all reconciliation sources under a
        specific context. You can filter the results by source type. The
        response uses cursor-based pagination.
      operationId: listSources
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: Filter by source type
          in: query
          name: type
          schema:
            type: string
            enum:
              - LEDGER
              - BANK
              - GATEWAY
              - CUSTOM
      responses:
        '200':
          description: List of sources with cursor pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSourcesResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: List reconciliation sources
      tags:
        - Configuration Sources
    post:
      description: >-
        Use this endpoint to create a new reconciliation source under a specific
        context. Sources define where transaction data comes from for
        reconciliation.
      operationId: createSource
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSourceRequest'
        description: Source creation payload
        required: true
      responses:
        '201':
          description: >-
            Successfully created source.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationSourceResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Create a reconciliation source
      tags:
        - Configuration Sources
  /v1/contexts/{contextId}/sources/{sourceId}:
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific reconciliation
        source by its identifier.
      operationId: getSource
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationSourceResponse'
        '400':
          description: Invalid source ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Get a reconciliation source
      tags:
        - Configuration Sources
    patch:
      description: >-
        Use this endpoint to update the fields of a specific reconciliation
        source by its identifier.
      operationId: updateSource
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSourceRequest'
        description: Source updates
        required: true
      responses:
        '200':
          description: >-
            Successfully updated source.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationSourceResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Update a reconciliation source
      tags:
        - Configuration Sources
  /v1/contexts/{contextId}/sources/{sourceId}/field-maps:
    get:
      description: >-
        Use this endpoint to retrieve the field map for a specific source within
        a context. Field maps define how source fields are mapped to
        reconciliation fields.
      operationId: getFieldMapBySource
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved field map
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldMapResponse'
        '400':
          description: Invalid source ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Field map not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Get a field map by source
      tags:
        - Configuration Field Maps
    post:
      description: >-
        Use this endpoint to create a field map for a specific source within a
        context. Field maps define how source fields are mapped to
        reconciliation fields.
      operationId: createFieldMap
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFieldMapRequest'
        description: Field map creation payload
        required: true
      responses:
        '201':
          description: >-
            Successfully created field map.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldMapResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context or source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Create a field map
      tags:
        - Configuration Field Maps
  /v1/field-maps/{fieldMapId}:
    delete:
      description: Use this endpoint to delete a specific field map by its identifier.
      operationId: deleteFieldMap
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the field map.
          in: path
          name: fieldMapId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Field map successfully deleted
        '400':
          description: Invalid field map ID
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Field map not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Delete a field map
      tags:
        - Configuration Field Maps
    patch:
      description: >-
        Use this endpoint to update the fields of a specific field map by its
        identifier.
      operationId: updateFieldMap
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the field map.
          in: path
          name: fieldMapId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFieldMapRequest'
        description: Field map updates
        required: true
      responses:
        '200':
          description: >-
            Successfully updated field map.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldMapResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Field map not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Update a field map
      tags:
        - Configuration Field Maps
  /v1/fee-schedules:
    get:
      description: >-
        Use this endpoint to retrieve all fee schedules for the authenticated
        tenant.
      operationId: listFeeSchedules
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
      responses:
        '200':
          description: List of fee schedules with cursor pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFeeSchedulesResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List fee schedules
      tags:
        - Configuration Fee Schedules
    post:
      description: >-
        Use this endpoint to create a new fee schedule. Fee schedules define the
        fee structure applied to transactions during reconciliation.
      operationId: createFeeSchedule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeeScheduleRequest'
        description: Fee schedule creation payload
        required: true
      responses:
        '201':
          description: >-
            Successfully created fee schedule.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeScheduleResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Create a fee schedule
      tags:
        - Configuration Fee Schedules
  /v1/fee-schedules/{scheduleId}:
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific fee schedule by
        its identifier.
      operationId: getFeeSchedule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the fee schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved fee schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeScheduleResponse'
        '400':
          description: Invalid schedule ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Fee schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get a fee schedule
      tags:
        - Configuration Fee Schedules
    patch:
      description: >-
        Use this endpoint to update the fields of a specific fee schedule by its
        identifier.
      operationId: updateFeeSchedule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the fee schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFeeScheduleRequest'
        description: Fee schedule updates
        required: true
      responses:
        '200':
          description: >-
            Successfully updated fee schedule.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeScheduleResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Fee schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Update a fee schedule
      tags:
        - Configuration Fee Schedules
    delete:
      description: Use this endpoint to delete a specific fee schedule by its identifier.
      operationId: deleteFeeSchedule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the fee schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Fee schedule successfully deleted
        '400':
          description: Invalid schedule ID
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Fee schedule not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The request conflicts with the current state of the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorFeeScheduleInUse:
                  $ref: '#/components/examples/ErrorFeeScheduleInUse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Delete a fee schedule
      tags:
        - Configuration Fee Schedules
  /v1/fee-schedules/{scheduleId}/simulate:
    post:
      description: >-
        Use this endpoint to simulate fee calculation for a given gross amount
        using a specific fee schedule. Returns the net amount, total fee, and
        per-item breakdown.
      operationId: simulateFeeSchedule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the fee schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateFeeRequest'
        description: Fee simulation payload
        required: true
      responses:
        '200':
          description: >-
            Fee simulation result.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateFeeResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Fee schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Simulate fee calculation
      tags:
        - Configuration Fee Schedules
  /v1/contexts/{contextId}/schedules:
    get:
      description: >-
        Use this endpoint to retrieve all reconciliation schedules for a
        specific context.
      operationId: listSchedules
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          description: List of schedules for the context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSchedulesResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List schedules for a context
      tags:
        - Configuration Schedules
    post:
      description: >-
        Use this endpoint to create a cron-based reconciliation schedule for
        automatic matching within a context.
      operationId: createSchedule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduleRequest'
        description: Schedule details
        required: true
      responses:
        '201':
          description: >-
            Schedule created.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Create a schedule
      tags:
        - Configuration Schedules
  /v1/contexts/{contextId}/schedules/{scheduleId}:
    get:
      description: >-
        Use this endpoint to retrieve a specific reconciliation schedule by its
        identifier.
      operationId: getSchedule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schedule details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get a schedule
      tags:
        - Configuration Schedules
    patch:
      description: >-
        Use this endpoint to update an existing reconciliation schedule. You can
        modify the cron expression and enabled status.
      operationId: updateSchedule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduleRequest'
        description: Fields to update
        required: true
      responses:
        '200':
          description: >-
            Schedule updated.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Update a schedule
      tags:
        - Configuration Schedules
    delete:
      description: Use this endpoint to delete a reconciliation schedule from a context.
      operationId: deleteSchedule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Schedule deleted
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Delete a schedule
      tags:
        - Configuration Schedules
  /v1/contexts/{contextId}/fee-rules:
    get:
      description: >-
        Use this endpoint to retrieve all fee rules for a reconciliation
        context, ordered by priority.
      operationId: listFeeRules
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of fee rules for the context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFeeRulesResponse'
        '400':
          description: Invalid context ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List fee rules
      tags:
        - Configuration Fee Rules
    post:
      description: >
        Use this endpoint to create a new fee rule that maps transaction
        metadata to a fee schedule within a context.


        Priority must be unique within a context across all sides (LEFT, RIGHT,
        and ANY rules share the same priority space). The caller must also be
        allowed to read the referenced fee schedule.
      operationId: createFeeRule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeeRuleRequest'
        description: Fee rule creation payload
        required: true
      responses:
        '201':
          description: >-
            Successfully created fee rule.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeRuleResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — duplicate priority or name within this context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Create a fee rule
      tags:
        - Configuration Fee Rules
  /v1/fee-rules/{feeRuleId}:
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific fee rule by its
        identifier.
      operationId: getFeeRule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the fee rule.
          in: path
          name: feeRuleId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved fee rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeRuleResponse'
        '400':
          description: Invalid fee rule ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Fee rule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get a fee rule
      tags:
        - Configuration Fee Rules
    patch:
      description: >-
        Use this endpoint to update the fields of a specific fee rule by its
        identifier. If the referenced fee schedule changes, the caller must also
        be allowed to read that fee schedule.
      operationId: updateFeeRule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the fee rule.
          in: path
          name: feeRuleId
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFeeRuleRequest'
        description: Fee rule updates
        required: true
      responses:
        '200':
          description: >-
            Successfully updated fee rule.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeeRuleResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Fee rule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — duplicate priority or name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Update a fee rule
      tags:
        - Configuration Fee Rules
    delete:
      description: Use this endpoint to permanently remove a fee rule by its identifier.
      operationId: deleteFeeRule
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the fee rule.
          in: path
          name: feeRuleId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Fee rule successfully deleted
        '400':
          description: Invalid fee rule ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Fee rule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Delete a fee rule
      tags:
        - Configuration Fee Rules
  /v1/contexts/{contextId}/export-jobs:
    get:
      description: >-
        Use this endpoint to list all export jobs for a specific reconciliation
        context. Supports cursor-based pagination.
      operationId: listExportJobsByContext
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          description: List of export jobs for the context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobListResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List export jobs by context
      tags:
        - Export Jobs
    post:
      description: >-
        Use this endpoint to create an asynchronous export job for large report
        exports. Supported formats include CSV, JSON, and XML.
      operationId: createExportJob
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExportJobRequest'
        description: Export job parameters
        required: true
      responses:
        '202':
          description: >-
            Indicates that the request was accepted for processing.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateExportJobResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0702:
                  $ref: '#/components/examples/ErrorM0702'
      security:
        - BearerAuth: []
      summary: Create an export job
      tags:
        - Export Jobs
  /v1/disputes:
    get:
      description: >-
        Use this endpoint to retrieve all disputes. Supports filtering by state,
        category, and date range with cursor-based pagination.
      operationId: listDisputes
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: Filter by dispute state
          in: query
          name: state
          schema:
            type: string
            enum:
              - DRAFT
              - OPEN
              - PENDING_EVIDENCE
              - WON
              - LOST
        - description: Filter by dispute category
          in: query
          name: category
          schema:
            type: string
            enum:
              - BANK_FEE_ERROR
              - UNRECOGNIZED_CHARGE
              - DUPLICATE_TRANSACTION
              - OTHER
        - description: Start date filter (RFC 3339 format)
          in: query
          name: date_from
          schema:
            type: string
            format: date-time
        - description: End date filter (RFC 3339 format)
          in: query
          name: date_to
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: List of disputes with cursor pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDisputesResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: List disputes
      tags:
        - Exception
  /v1/disputes/{disputeId}:
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific dispute by its
        identifier, including its current state, category, and any submitted
        evidence.
      operationId: getDispute
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the dispute.
          in: path
          name: disputeId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved dispute
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Dispute not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Get a dispute
      tags:
        - Exception
  /v1/disputes/{disputeId}/close:
    post:
      description: >-
        Use this endpoint to close a dispute with a resolution. The dispute can
        be marked as won or lost based on the outcome.
      operationId: closeDispute
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
        - description: Dispute ID
          in: path
          name: disputeId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloseDisputeRequest'
        description: Close dispute payload
        required: true
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The request was well-formed but contains semantic errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Close a dispute
      tags:
        - Exception
  /v1/disputes/{disputeId}/evidence:
    post:
      description: >-
        Use this endpoint to add evidence to a dispute. Evidence can include
        comments and optional file attachments to support the dispute case.
      operationId: submitEvidence
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
        - description: Dispute ID
          in: path
          name: disputeId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitEvidenceRequest'
        description: Submit evidence payload
        required: true
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The request was well-formed but contains semantic errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Submit evidence to a dispute
      tags:
        - Exception
  /v1/exceptions:
    get:
      description: >-
        Use this endpoint to retrieve all exceptions. You can filter the results
        by status, severity, assigned user, external system, and date range. The
        response uses cursor-based pagination.
      operationId: listExceptions
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Filter by status
          in: query
          name: status
          schema:
            type: string
            enum:
              - OPEN
              - ASSIGNED
              - PENDING_RESOLUTION
              - RESOLVED
        - description: Filter by severity
          in: query
          name: severity
          schema:
            type: string
            enum:
              - LOW
              - MEDIUM
              - HIGH
              - CRITICAL
        - description: Filter by assigned user
          in: query
          name: assigned_to
          schema:
            type: string
        - description: Filter by external system
          in: query
          name: external_system
          schema:
            type: string
            enum:
              - JIRA
              - SERVICENOW
              - WEBHOOK
        - description: Filter from date (RFC3339)
          in: query
          name: date_from
          schema:
            type: string
        - description: Filter to date (RFC3339)
          in: query
          name: date_to
          schema:
            type: string
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: Number of items per page
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The field used to sort the results.
          in: query
          name: sort_by
          schema:
            type: string
            enum:
              - id
              - created_at
              - updated_at
              - severity
              - status
            default: id
        - description: The order used to sort the results.
          in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListExceptionsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List exceptions
      tags:
        - Exception
  /v1/exceptions/bulk/assign:
    post:
      description: >-
        Use this endpoint to assign multiple exceptions to a team member in a
        single operation. You can assign up to 100 exceptions at a time.
      operationId: bulkAssignExceptions
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkAssignRequest'
        description: Bulk assign payload
        required: true
      responses:
        '200':
          description: >-
            Bulk operation completed (check response for partial failures).


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkActionResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Bulk assign exceptions
      tags:
        - Exception
  /v1/exceptions/bulk/dispatch:
    post:
      description: >-
        Use this endpoint to dispatch multiple exceptions to an external system
        in a single operation. You can dispatch up to 100 exceptions at a time.
      operationId: bulkDispatchExceptions
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDispatchRequest'
        description: Bulk dispatch payload
        required: true
      responses:
        '200':
          description: >-
            Bulk operation completed (check response for partial failures).


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkActionResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Bulk dispatch exceptions
      tags:
        - Exception
  /v1/exceptions/bulk/resolve:
    post:
      description: >-
        Use this endpoint to resolve multiple exceptions in a single operation.
        You can resolve up to 100 exceptions at a time with a shared resolution
        and reason.
      operationId: bulkResolveExceptions
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkResolveRequest'
        description: Bulk resolve payload
        required: true
      responses:
        '200':
          description: >-
            Bulk operation completed (check response for partial failures).


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkActionResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Bulk resolve exceptions
      tags:
        - Exception
  /v1/exceptions/{exceptionId}:
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific exception by its
        identifier.
      operationId: getException
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get exception
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/adjust-entry:
    post:
      description: >-
        Use this endpoint to resolve an exception by creating an adjustment
        entry. This is used when a monetary correction is needed to reconcile
        the transaction.
      operationId: adjustEntryException
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustEntryRequest'
        description: Adjust entry payload
        required: true
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The request was well-formed but contains semantic errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Adjust entry for an exception
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/dispatch:
    post:
      description: >-
        Use this endpoint to dispatch an exception to an external ticketing
        system such as JIRA or ServiceNow for tracking and resolution.
      operationId: dispatchException
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchRequest'
        description: Dispatch payload
        required: true
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DispatchResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The request was well-formed but contains semantic errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Dispatch exception to external system
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/callback:
    post:
      description: >-
        Use this endpoint to process a callback from an external system for a
        dispatched exception. This updates the exception status based on the
        external system resolution.
      operationId: processCallback
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
        - description: The unique identifier of the exception.
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessCallbackRequest'
        description: Callback payload from external system
        required: true
      responses:
        '200':
          description: >-
            Callback processed successfully.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessCallbackResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Exception not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The request conflicts with the current state of the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorExceptionCallbackInUse:
                  $ref: '#/components/examples/ErrorExceptionCallbackInUse'
        '429':
          description: Too many requests. The rate limit has been exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0701:
                  $ref: '#/components/examples/ErrorM0701'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Process exception callback
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/disputes:
    post:
      description: >-
        Use this endpoint to open a new dispute for an exception. Disputes are
        used to formally challenge or investigate discrepancies with external
        parties.
      operationId: openDispute
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenDisputeRequest'
        description: Open dispute payload
        required: true
      responses:
        '201':
          description: >-
            Indicates that the resource was successfully created.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Open a dispute
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/comments:
    get:
      description: >-
        Use this endpoint to retrieve all comments for a specific exception.
        Comments provide an audit trail of team discussions and decisions.
      operationId: listComments
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the exception.
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of comments for the exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCommentsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Exception not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: List exception comments
      tags:
        - Exception
    post:
      description: >-
        Use this endpoint to add a comment to a specific exception. Comments
        help track team discussions, decisions, and investigation notes.
      operationId: addComment
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the exception.
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCommentRequest'
        description: Comment payload
        required: true
      responses:
        '201':
          description: >-
            Comment added successfully.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Exception not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Add a comment to an exception
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/comments/{commentId}:
    delete:
      description: Use this endpoint to delete a specific comment from an exception.
      operationId: deleteComment
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the exception.
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
        - description: The unique identifier of the comment.
          in: path
          name: commentId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Comment successfully deleted
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Comment or exception not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Delete an exception comment
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/force-match:
    post:
      description: >-
        Use this endpoint to resolve an exception by forcing a match with an
        override reason. This is used when manual intervention determines the
        transaction should be considered matched despite discrepancies.
      operationId: forceMatchException
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForceMatchRequest'
        description: Force match payload
        required: true
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The request was well-formed but contains semantic errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Force match an exception
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/history:
    get:
      description: >-
        Use this endpoint to retrieve the audit history for an exception. The
        history shows all actions taken on the exception.
      operationId: getExceptionHistory
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            type: string
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: Number of items per page
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoryResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get exception history
      tags:
        - Exception
  /v1/export-jobs:
    get:
      description: >-
        Use this endpoint to retrieve all export jobs for the authenticated
        tenant.
      operationId: listExportJobs
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: >-
            Filter by status (QUEUED, RUNNING, SUCCEEDED, FAILED, EXPIRED,
            CANCELED)
          in: query
          name: status
          schema:
            type: string
        - description: Maximum number of jobs to return (default 20, max 100)
          in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobListResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List export jobs
      tags:
        - Export Jobs
  /v1/export-jobs/{jobId}:
    get:
      description: Use this endpoint to retrieve the status of a specific export job.
      operationId: getExportJob
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Export Job ID
          in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get export job status
      tags:
        - Export Jobs
  /v1/export-jobs/{jobId}/cancel:
    post:
      description: Use this endpoint to cancel a queued or running export job.
      operationId: cancelExportJob
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Export Job ID
          in: path
          name: jobId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Job in terminal state or idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Cancel an export job
      tags:
        - Export Jobs
  /v1/export-jobs/{jobId}/download:
    get:
      description: >-
        Use this endpoint to download the export file. The response includes a
        presigned URL for downloading the file.
      operationId: downloadExportJob
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Export Job ID
          in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Export download details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadExportJobResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Job not ready for download
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0703:
                  $ref: '#/components/examples/ErrorM0703'
      security:
        - BearerAuth: []
      summary: Download export file
      tags:
        - Export Jobs
  /v1/governance/audit-logs:
    get:
      description: >-
        Use this endpoint to retrieve all audit log entries. You can filter the
        results by actor, date range, action type, and entity type. The response
        uses cursor-based pagination.
      operationId: listAuditLogs
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Filter by actor ID
          in: query
          name: actor
          schema:
            type: string
        - description: Filter logs from this date (YYYY-MM-DD or RFC3339)
          in: query
          name: date_from
          schema:
            type: string
        - description: Filter logs until this date (YYYY-MM-DD or RFC3339)
          in: query
          name: date_to
          schema:
            type: string
        - description: Filter by action type
          example: CREATE
          in: query
          name: action
          schema:
            type: string
        - description: Filter by entity type
          example: reconciliation_context
          in: query
          name: entity_type
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAuditLogsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List audit logs
      tags:
        - Governance
  /v1/governance/audit-logs/{id}:
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific audit log entry
        by its identifier. Audit logs contain immutable records of all system
        operations for compliance and debugging purposes.
      operationId: getAuditLog
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Audit Log ID
          in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get audit log by ID
      tags:
        - Governance
  /v1/governance/entities/{entityType}/{entityId}/audit-logs:
    get:
      description: >-
        Use this endpoint to retrieve all audit log entries for a specific
        entity. The results are ordered by creation time descending. This allows
        you to trace the complete change history of any entity in the system.
      operationId: listAuditLogsByEntity
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Entity type
          example: reconciliation_context
          in: path
          name: entityType
          required: true
          schema:
            type: string
        - description: Entity ID
          in: path
          name: entityId
          required: true
          schema:
            type: string
            format: uuid
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAuditLogsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List audit logs by entity
      tags:
        - Governance
  /v1/governance/actor-mappings/{actorId}:
    put:
      description: >-
        Use this endpoint to create or update an actor mapping. Actor mappings
        associate system actor identifiers with human-readable display names and
        email addresses for audit log readability.
      operationId: upsertActorMapping
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The actor identifier to map.
          in: path
          name: actorId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertActorMappingRequest'
        description: Actor mapping payload
        required: true
      responses:
        '200':
          description: >-
            Actor mapping created or updated.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActorMappingResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Upsert an actor mapping
      tags:
        - Governance
    get:
      description: >-
        Use this endpoint to retrieve the display name and email mapped to a
        specific actor identifier.
      operationId: getActorMapping
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The actor identifier.
          in: path
          name: actorId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved actor mapping
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActorMappingResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0103:
                  $ref: '#/components/examples/ErrorM0103'
        '404':
          description: Actor mapping not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Get an actor mapping
      tags:
        - Governance
    delete:
      description: Use this endpoint to delete an actor mapping by its identifier.
      operationId: deleteActorMapping
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The actor identifier.
          in: path
          name: actorId
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Actor mapping successfully deleted
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Actor mapping not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Delete an actor mapping
      tags:
        - Governance
  /v1/governance/actor-mappings/{actorId}/pseudonymize:
    post:
      description: >-
        Use this endpoint to pseudonymize an actor by replacing their display
        name and email with "[REDACTED]". This supports GDPR right-to-erasure
        compliance. This action is irreversible.
      operationId: pseudonymizeActor
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The actor identifier to pseudonymize.
          in: path
          name: actorId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      responses:
        '204':
          description: >-
            Actor successfully pseudonymized.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Actor mapping not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Pseudonymize an actor
      tags:
        - Governance
  /v1/governance/archives:
    get:
      description: >-
        Use this endpoint to list all audit log archives. Archives contain
        historical audit log data that has been compressed and moved to
        long-term storage. Supports offset-based pagination.
      operationId: listArchives
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The number of items to skip before returning results.
          in: query
          name: offset
          schema:
            type: integer
            minimum: 0
            default: 0
        - description: Start date filter (YYYY-MM-DD or RFC 3339 format)
          in: query
          name: from
          schema:
            type: string
        - description: End date filter (YYYY-MM-DD or RFC 3339 format)
          in: query
          name: to
          schema:
            type: string
      responses:
        '200':
          description: List of audit log archives
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListArchivesResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: List audit log archives
      tags:
        - Governance
  /v1/governance/archives/{id}/download:
    get:
      description: >-
        Use this endpoint to download an audit log archive. Returns a pre-signed
        URL with a time-limited download link and a SHA-256 checksum for
        integrity verification.
      operationId: downloadArchive
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the archive.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Archive download details with pre-signed URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveDownloadResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0001:
                  $ref: '#/components/examples/ErrorM0001'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Archive not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
        '503':
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0703:
                  $ref: '#/components/examples/ErrorM0703'
      security:
        - BearerAuth: []
      summary: Download an audit log archive
      tags:
        - Governance
  /v1/imports/contexts/{contextId}/jobs:
    get:
      description: >-
        Use this endpoint to retrieve all ingestion jobs for a specific
        reconciliation context. You can sort the results by various fields. The
        response uses cursor-based pagination.
      operationId: listIngestionJobs
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: The order used to sort the results.
          in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
        - description: The field used to sort the results.
          in: query
          name: sort_by
          schema:
            type: string
            enum:
              - id
              - created_at
              - started_at
              - completed_at
              - status
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListJobsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List ingestion jobs for a context
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/jobs/{jobId}:
    get:
      description: >-
        Use this endpoint to retrieve the status and details of a specific
        ingestion job by its identifier. The response includes progress metrics
        and error information.
      operationId: getIngestionJob
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Job ID
          in: path
          name: jobId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get ingestion job status
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/jobs/{jobId}/transactions:
    get:
      description: >-
        Use this endpoint to retrieve all transactions extracted from an
        ingestion job. You can sort the results by various fields. The response
        uses cursor-based pagination.
      operationId: listJobTransactions
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Job ID
          in: path
          name: jobId
          required: true
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: The order used to sort the results.
          in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
        - description: The field used to sort the results.
          in: query
          name: sort_by
          schema:
            type: string
            enum:
              - id
              - created_at
              - date
              - status
              - extraction_status
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTransactionsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List transactions for a job
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/sources/{sourceId}/upload:
    post:
      description: >-
        Use this endpoint to upload a transaction file (CSV, JSON, or XML) for
        ingestion into a reconciliation context. The file is parsed, validated,
        and transactions are extracted for matching.
      operationId: uploadFile
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: Transaction file (CSV, JSON, or XML)
                  type: string
                  format: binary
                format:
                  description: File format
                  type: string
                  enum:
                    - csv
                    - json
                    - xml
              required:
                - file
                - format
        required: true
      responses:
        '202':
          description: >-
            Indicates that the request was accepted for processing.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Idempotency conflict: request with same key in progress'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: The uploaded file exceeds the maximum allowed size.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0801:
                  $ref: '#/components/examples/ErrorM0801'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Upload transaction file
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/sources/{sourceId}/preview:
    post:
      description: >-
        Use this endpoint to preview a transaction file before importing it.
        Returns sample rows and detected columns to help verify the file
        structure and field mapping.
      operationId: previewFile
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: Transaction file to preview (CSV, JSON, or XML)
                  type: string
                  format: binary
                format:
                  description: File format (auto-detected from filename if omitted)
                  type: string
                  enum:
                    - csv
                    - json
                    - xml
                max_rows:
                  description: Maximum number of sample rows to return
                  type: integer
                  minimum: 1
                  maximum: 20
                  default: 5
              required:
                - file
        required: true
      responses:
        '200':
          description: >-
            File preview with detected columns and sample rows.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilePreviewResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Context or source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Preview a transaction file
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/transactions/{transactionId}/ignore:
    post:
      description: >-
        Use this endpoint to mark a transaction as "Do Not Match" with a
        required reason. Only UNMATCHED transactions can be ignored.
      operationId: ignoreTransaction
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
            format: uuid
        - description: The unique identifier of the transaction.
          in: path
          name: transactionId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IgnoreTransactionRequest'
        description: Ignore transaction request
        required: true
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IgnoreTransactionResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Transaction already matched/ignored or idempotency conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Ignore a transaction
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/transactions/search:
    get:
      description: >-
        Use this endpoint to search transactions within a reconciliation
        context. Supports free-text search, amount range filters, date filters,
        and status filters with offset-based pagination.
      operationId: searchTransactions
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Free-text search query
          in: query
          name: q
          schema:
            type: string
        - description: Minimum transaction amount
          in: query
          name: amount_min
          schema:
            type: string
        - description: Maximum transaction amount
          in: query
          name: amount_max
          schema:
            type: string
        - description: Start date filter (RFC 3339 format)
          in: query
          name: date_from
          schema:
            type: string
            format: date-time
        - description: End date filter (RFC 3339 format)
          in: query
          name: date_to
          schema:
            type: string
            format: date-time
        - description: Transaction reference (exact match)
          in: query
          name: reference
          schema:
            type: string
        - description: Currency code filter
          in: query
          name: currency
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
        - description: Transaction status filter
          in: query
          name: status
          schema:
            type: string
            enum:
              - UNMATCHED
              - MATCHED
              - IGNORED
              - PENDING_REVIEW
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - description: The number of items to skip before returning results.
          in: query
          name: offset
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Search results with offset pagination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchTransactionsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Search transactions
      tags:
        - Ingestion
  /v1/matching/adjustments:
    post:
      description: >-
        Use this endpoint to create a balancing journal entry (e.g., bank fee,
        FX difference) to resolve variance between matched transactions or on a
        single transaction.
      operationId: createAdjustment
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Context ID
          in: query
          name: contextId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAdjustmentRequest'
        description: Adjustment payload
        required: true
      responses:
        '201':
          description: >-
            Indicates that the resource was successfully created.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdjustmentResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Create an adjustment
      tags:
        - Matching
  /v1/matching/contexts/{contextId}/run:
    post:
      description: >-
        Use this endpoint to trigger a matching run for a reconciliation
        context. You can use DRY_RUN mode to test rules without committing
        results, or COMMIT mode to persist matches.
      operationId: runMatch
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunMatchRequest'
        description: Run match payload
        required: true
      responses:
        '202':
          description: >-
            Indicates that the request was accepted for processing.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunMatchResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Trigger a matching run
      tags:
        - Matching
  /v1/matching/contexts/{contextId}/runs:
    get:
      description: >-
        Use this endpoint to retrieve all match runs for a specific
        reconciliation context. The results are sorted by creation time
        descending.
      operationId: listMatchRuns
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: The order used to sort the results.
          in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMatchRunsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List match runs
      tags:
        - Matching
  /v1/matching/groups/{matchGroupId}:
    delete:
      description: >-
        Use this endpoint to break an incorrect match group. This rejects the
        match with a reason and reverts all associated transactions to UNMATCHED
        status.
      operationId: unmatch
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Match Group ID
          in: path
          name: matchGroupId
          required: true
          schema:
            type: string
        - description: Context ID
          in: query
          name: contextId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnmatchRequest'
        description: Unmatch payload with rejection reason
        required: true
      responses:
        '204':
          description: >-
            Indicates that the operation was successful with no content to
            return.
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Break/Unmatch a match group
      tags:
        - Matching
  /v1/matching/manual:
    post:
      description: >-
        Use this endpoint to manually link multiple transactions (at least 2)
        into a match group with 100% confidence. Transactions must be UNMATCHED
        and belong to the specified context.
      operationId: createManualMatch
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Context ID
          in: query
          name: contextId
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/XIdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateManualMatchRequest'
        description: Manual match payload
        required: true
      responses:
        '201':
          description: >-
            Indicates that the resource was successfully created.


            The response includes the `X-Idempotency-Replayed` header.


            If the value is false, the request was just processed. If the value
            is true, the response is a replay of a previously processed request.


            See [Retries and idempotency](/en/reference/retries-idempotency) for
            more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManualMatchResponse'
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Create a manual match
      tags:
        - Matching
  /v1/matching/runs/{runId}:
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific match run by its
        identifier. The response includes status, timing, and aggregate
        statistics.
      operationId: getMatchRun
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Run ID
          in: path
          name: runId
          required: true
          schema:
            type: string
        - description: Context ID
          in: query
          name: contextId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchRunResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get match run
      tags:
        - Matching
  /v1/matching/runs/{runId}/groups:
    get:
      description: >-
        Use this endpoint to retrieve all match groups from a specific matching
        run. Each group contains matched transaction pairs and confidence
        scores. The response uses cursor-based pagination.
      operationId: getMatchRunGroups
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: Run ID
          in: path
          name: runId
          required: true
          schema:
            type: string
        - description: Context ID
          in: query
          name: contextId
          required: true
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: The order used to sort the results.
          in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
        - description: The field used to sort the results.
          in: query
          name: sort_by
          schema:
            type: string
            enum:
              - id
              - created_at
              - status
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMatchGroupsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get match run results
      tags:
        - Matching
  /v1/reports/contexts/{contextId}/dashboard:
    get:
      description: >-
        Use this endpoint to retrieve combined dashboard aggregates including
        volume, match rate, and SLA statistics.
      operationId: getDashboardAggregates
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardAggregatesResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get all dashboard aggregates
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/dashboard/match-rate:
    get:
      description: >-
        Use this endpoint to retrieve match rate percentage and trend data for a
        reconciliation context within the specified date range.
      operationId: getMatchRateStats
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchRateStatsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get match rate statistics
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/dashboard/metrics:
    get:
      description: >-
        Use this endpoint to retrieve complete dashboard metrics including
        summary, trends, and breakdowns for the Command Center.
      operationId: getMatcherDashboardMetrics
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatcherDashboardMetricsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get comprehensive dashboard metrics
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/dashboard/sla:
    get:
      description: >-
        Use this endpoint to retrieve SLA compliance statistics for a
        reconciliation context within the specified date range.
      operationId: getSLAStats
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SLAStatsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get SLA statistics
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/dashboard/volume:
    get:
      description: >-
        Use this endpoint to retrieve transaction volume statistics for a
        reconciliation context within the specified date range.
      operationId: getVolumeStats
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeStatsResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get volume statistics
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/dashboard/source-breakdown:
    get:
      description: >-
        Use this endpoint to retrieve a breakdown of reconciliation metrics by
        source for a specific context and date range. Shows match rates,
        transaction counts, and unmatched amounts per source.
      operationId: getSourceBreakdown
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: Source breakdown metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceBreakdownListResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Get source breakdown
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/dashboard/cash-impact:
    get:
      description: >-
        Use this endpoint to retrieve a cash impact summary showing the total
        unmatched financial exposure. Includes breakdowns by currency and by age
        bucket to help prioritize resolution efforts.
      operationId: getCashImpactSummary
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: Cash impact summary with currency and age breakdowns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashImpactSummaryResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Get cash impact summary
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/exceptions/count:
    get:
      description: >-
        Use this endpoint to retrieve the total number of exceptions for a
        specific context and date range.
      operationId: countExceptions
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: Exception count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportCountResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Count exceptions
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/exceptions/export:
    get:
      description: >-
        Use this endpoint to export an exceptions report in CSV or PDF format
        for the specified date range.
      operationId: exportExceptionsReport
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
        - description: Export format (csv or pdf)
          in: query
          name: format
          schema:
            type: string
            enum:
              - csv
              - pdf
            default: csv
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            text/csv:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Export exceptions report
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/matches/count:
    get:
      description: >-
        Use this endpoint to retrieve the total number of matched items for a
        specific context and date range.
      operationId: countMatched
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: Match count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportCountResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Count matches
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/transactions/count:
    get:
      description: >-
        Use this endpoint to retrieve the total number of transactions for a
        specific context and date range.
      operationId: countTransactions
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: Transaction count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportCountResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Count transactions
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/unmatched/count:
    get:
      description: >-
        Use this endpoint to retrieve the total number of unmatched items for a
        specific context and date range.
      operationId: countUnmatched
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: Unmatched count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportCountResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0201:
                  $ref: '#/components/examples/ErrorM0201'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Count unmatched items
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/matched:
    get:
      description: >-
        Use this endpoint to retrieve a paginated list of matched transactions
        for a specific context and date range. The response uses cursor-based
        pagination.
      operationId: getMatchedReport
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
            format: uuid
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
            format: date
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
            format: date
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: Sort order by date
          in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Paginated list of matched transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMatchedReportResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: List matched transactions report
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/matched/export:
    get:
      description: >-
        Use this endpoint to export a matched transactions report in CSV or PDF
        format for the specified date range.
      operationId: exportMatchedReport
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
        - description: Export format (csv or pdf)
          in: query
          name: format
          schema:
            type: string
            enum:
              - csv
              - pdf
            default: csv
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            text/csv:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Export matched transactions report
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/summary:
    get:
      description: >-
        Use this endpoint to retrieve an aggregated reconciliation summary for a
        specific context and date range, including matched and unmatched counts
        and amounts.
      operationId: getSummaryReport
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
            format: uuid
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
            format: date
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
            format: date
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
      responses:
        '200':
          description: Aggregated reconciliation summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryReportResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: Get reconciliation summary report
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/summary/export:
    get:
      description: >-
        Use this endpoint to export a reconciliation summary report in CSV or
        PDF format for the specified date range.
      operationId: exportSummaryReport
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
        - description: Export format (csv or pdf)
          in: query
          name: format
          schema:
            type: string
            enum:
              - csv
              - pdf
            default: csv
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            text/csv:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Export summary report
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/unmatched:
    get:
      description: >-
        Use this endpoint to retrieve a paginated list of unmatched transactions
        for a specific context and date range. The response uses cursor-based
        pagination.
      operationId: getUnmatchedReport
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
            format: uuid
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
            format: date
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
            format: date
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: Sort order by date
          in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Paginated list of unmatched transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUnmatchedReportResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: List unmatched transactions report
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/unmatched/export:
    get:
      description: >-
        Use this endpoint to export an unmatched transactions report in CSV or
        PDF format for the specified date range.
      operationId: exportUnmatchedReport
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
        - description: Export format (csv or pdf)
          in: query
          name: format
          schema:
            type: string
            enum:
              - csv
              - pdf
            default: csv
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            text/csv:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Export unmatched transactions report
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/variance:
    get:
      description: >-
        Use this endpoint to retrieve a paginated variance analysis report for a
        specific context and date range. The response uses cursor-based
        pagination.
      operationId: getVarianceReport
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
            format: uuid
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
            format: date
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
            format: date
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
        - description: The cursor value for retrieving the next page of results.
          in: query
          name: cursor
          schema:
            type: string
        - description: The maximum number of items to include in the response.
          in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - description: Sort order by date
          in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Paginated variance analysis report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVarianceReportResponse'
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ErrorM0002:
                  $ref: '#/components/examples/ErrorM0002'
      security:
        - BearerAuth: []
      summary: List variance report
      tags:
        - Reporting
  /v1/reports/contexts/{contextId}/variance/export:
    get:
      description: >-
        Use this endpoint to export a variance analysis report in CSV or PDF
        format for the specified date range.
      operationId: exportVarianceReport
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            type: string
        - description: Start date (YYYY-MM-DD)
          in: query
          name: date_from
          required: true
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          in: query
          name: date_to
          required: true
          schema:
            type: string
        - description: Source ID filter
          in: query
          name: source_id
          schema:
            type: string
        - description: Export format (csv or pdf)
          in: query
          name: format
          schema:
            type: string
            enum:
              - csv
              - pdf
            default: csv
      responses:
        '200':
          description: >-
            Indicates that the request was successful and the response contains
            the expected data.
          content:
            text/csv:
              schema:
                type: string
                format: binary
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: The request contains invalid parameters or payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Export variance report
      tags:
        - Reporting
  /v1/discovery/status:
    get:
      description: >-
        Use this endpoint to retrieve the current Fetcher integration status,
        including whether the Fetcher service is healthy and how many
        connections have been discovered.
      operationId: getDiscoveryStatus
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
      responses:
        '200':
          description: Discovery status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryStatusResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get discovery status
      tags:
        - Discovery
  /v1/discovery/connections:
    get:
      description: >-
        Use this endpoint to retrieve all discovered Fetcher database
        connections available for the current tenant.
      operationId: listDiscoveryConnections
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
      responses:
        '200':
          description: List of discovered connections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionListResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: List discovered connections
      tags:
        - Discovery
    post:
      description: >-
        Provisions a Fetcher connection scoped to Matcher and synchronizes the
        local discovery cache.
      operationId: createDiscoveryConnection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionProvisioningRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Create discovery connection
      tags:
        - Discovery
  /v1/discovery/connections/{connectionId}:
    get:
      description: >-
        Use this endpoint to retrieve a single discovered Fetcher connection by
        its internal identifier.
      operationId: getDiscoveryConnection
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the connection.
          in: path
          name: connectionId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Connection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
        '400':
          description: Invalid connection ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Connection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get a discovered connection
      tags:
        - Discovery
    delete:
      description: >-
        Deletes a Matcher-owned Fetcher connection and marks the local cache
        unavailable.
      operationId: deleteDiscoveryConnection
      parameters:
        - description: Connection ID (UUID)
          in: path
          name: connectionId
          required: true
          schema:
            description: Connection ID (UUID)
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
            format: uuid
            type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Delete discovery connection
      tags:
        - Discovery
    patch:
      description: >-
        Updates a Matcher-owned Fetcher connection and synchronizes the local
        discovery cache.
      operationId: updateDiscoveryConnection
      parameters:
        - description: Matcher connection ID
          in: path
          name: connectionId
          required: true
          schema:
            description: Matcher connection ID
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectionUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Update discovery connection
      tags:
        - Discovery
  /v1/discovery/connections/{connectionId}/schema:
    get:
      description: >-
        Use this endpoint to retrieve all discovered table schemas for a
        specific connection.
      operationId: getDiscoveryConnectionSchema
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the connection.
          in: path
          name: connectionId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schema for the connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionSchemaResponse'
        '400':
          description: Invalid connection ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Connection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get connection schema
      tags:
        - Discovery
  /v1/discovery/connections/{connectionId}/test:
    post:
      description: >-
        Use this endpoint to test connectivity for a specific discovered
        connection owned by the current tenant.
      operationId: testDiscoveryConnection
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the connection.
          in: path
          name: connectionId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Test result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestConnectionResponse'
        '400':
          description: Invalid connection ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Connection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Fetcher service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Test a connection
      tags:
        - Discovery
  /v1/discovery/connections/{connectionId}/extractions:
    post:
      description: >-
        Use this endpoint to create an extraction request for a discovered
        connection and submit it to Fetcher for the authenticated tenant.
      operationId: startDiscoveryExtraction
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the connection.
          in: path
          name: connectionId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartExtractionRequest'
        description: Extraction request payload
        required: true
      responses:
        '201':
          description: Extraction request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionRequestResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Connection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Fetcher service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Start a connection extraction
      tags:
        - Discovery
  /v1/discovery/extractions/{extractionId}:
    get:
      description: >-
        Use this endpoint to retrieve the details of a specific extraction
        request by its identifier.
      operationId: getDiscoveryExtraction
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
        - description: The unique identifier of the extraction request.
          in: path
          name: extractionId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Extraction request details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionRequestResponse'
        '400':
          description: Invalid extraction ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Extraction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Get an extraction request
      tags:
        - Discovery
  /v1/discovery/refresh:
    post:
      description: >-
        Use this endpoint to force an immediate sync with the Fetcher service,
        updating the list of connections and their schemas.
      operationId: refreshDiscovery
      parameters:
        - description: A unique identifier for tracing the request across services.
          in: header
          name: X-Request-Id
          schema:
            type: string
      responses:
        '200':
          description: Refresh result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshDiscoveryResponse'
        '401':
          description: The request lacks valid authentication credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: You do not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A refresh is already in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Fetcher service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
      summary: Refresh discovery
      tags:
        - Discovery
  /v1/contexts/{contextId}/archive:
    post:
      description: >-
        Archives (soft-deletes) a reconciliation context by ID. Archiving flips
        the context to ARCHIVED in place and never erases its reconciled
        financial history; an archived context with children is valid. Archived
        contexts are excluded from the default listing. Use restore to bring it
        back to DRAFT.
      operationId: archiveContext
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Archive a reconciliation context
      tags:
        - Configuration
  /v1/contexts/{contextId}/field-maps:
    get:
      description: >-
        Returns a cursor-paginated list of every field map under a context,
        replacing per-source probing.
      operationId: listContextFieldMaps
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Maximum number of records to return
          explode: false
          in: query
          name: limit
          schema:
            default: 20
            description: Maximum number of records to return
            format: int64
            maximum: 200
            minimum: 1
            type: integer
        - description: Cursor for pagination (opaque)
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListContextFieldMapsResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List field maps for a context
      tags:
        - Configuration
  /v1/contexts/{contextId}/restore:
    post:
      description: >-
        Restores an archived reconciliation context back to DRAFT so it can be
        re-validated and re-activated. Restoring never auto-resumes matching.
        Restoring a context that is not archived is rejected with a 409
        invalid-state.
      operationId: restoreContext
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Restore an archived reconciliation context
      tags:
        - Configuration
  /v1/contexts/{contextId}/setup-progress:
    get:
      description: >-
        Returns configured-resource counts, last-run state, and activation
        readiness for a context in a single aggregate, so clients derive
        wizard/checklist state from one request.
      operationId: getSetupProgress
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupProgressResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Get context setup progress
      tags:
        - Configuration
  /v1/contexts/{contextId}/sources/{sourceId}/archive:
    post:
      description: >-
        Archives (soft-deletes) a reconciliation source by ID. Archiving never
        erases the source's imported transactions or field map; the source is
        simply excluded from listings, readiness counts, clone reads, and the
        matching working set. Use restore to bring it back.
      operationId: archiveSource
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Archive a reconciliation source
      tags:
        - Configuration
  /v1/contexts/{contextId}/sources/{sourceId}/bindings:
    get:
      description: >-
        Returns every source binding under a source's context, enabled and
        disabled, so a disabled binding stays visible instead of silently
        vanishing.
      operationId: listSourceBindings
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSourceBindingsResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List source bindings
      tags:
        - Configuration
    post:
      description: >-
        Creates a source binding tying a reconciliation source to a pull rail
        (file or query) plus an interval schedule. Exactly one rail payload is
        meaningful per kind: the file rail populates transportConfig, the query
        rail populates connectionId.
      operationId: createSourceBinding
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSourceBindingRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceBindingResponse'
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Create a source binding
      tags:
        - Configuration
  /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}:
    delete:
      description: Removes a source binding by ID.
      operationId: deleteSourceBinding
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
        - description: Binding ID
          in: path
          name: bindingId
          required: true
          schema:
            description: Binding ID
            format: uuid
            type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Delete a source binding
      tags:
        - Configuration
    get:
      description: Returns a source binding by ID.
      operationId: getSourceBinding
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
        - description: Binding ID
          in: path
          name: bindingId
          required: true
          schema:
            description: Binding ID
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceBindingResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Get a source binding
      tags:
        - Configuration
    patch:
      description: Updates fields on a source binding by ID. The rail (kind) is immutable.
      operationId: updateSourceBinding
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
        - description: Binding ID
          in: path
          name: bindingId
          required: true
          schema:
            description: Binding ID
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSourceBindingRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceBindingResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Update a source binding
      tags:
        - Configuration
  /v1/contexts/{contextId}/sources/{sourceId}/restore:
    post:
      description: >-
        Restores an archived reconciliation source back into the live working
        set.
      operationId: restoreSource
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Restore an archived reconciliation source
      tags:
        - Configuration
  /v1/discovery/aggregator-connections:
    get:
      description: >-
        Returns a cursor-paginated list of the tenant's Open-Finance
        data-aggregator (Pluggy/Belvo) connections, ordered by config name. The
        list is secret-free by construction: no credential material
        (clientId/secret/ciphertext) is ever returned.
      operationId: listAggregatorConnections
      parameters:
        - description: Maximum number of records to return
          explode: false
          in: query
          name: limit
          schema:
            default: 20
            description: Maximum number of records to return
            format: int64
            maximum: 200
            minimum: 1
            type: integer
        - description: Cursor for pagination (opaque)
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatorConnectionListResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List aggregator connections
      tags:
        - Discovery
    post:
      description: >-
        Creates an Open-Finance data-aggregator (Pluggy/Belvo) connection and
        seals its credential. The connection's config name is what the webhook
        token-mint endpoint binds a token to. The supplied credential is sealed
        before persistence and is never returned.
      operationId: createAggregatorConnection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregatorConnectionRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatorConnectionResponse'
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Create aggregator connection
      tags:
        - Discovery
  /v1/discovery/aggregator-connections/test:
    post:
      description: >-
        Runs a live connectivity check for an existing Open-Finance
        data-aggregator (Pluggy/Belvo) connection using its already-sealed
        credential, addressed by (vendor, configName). No credential is supplied
        or returned: the result is the secret-free boolean health of the
        connection.
      operationId: testAggregatorConnection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestAggregatorConnectionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestAggregatorConnectionResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Test aggregator connection credentials
      tags:
        - Discovery
  /v1/discovery/aggregator-connections/{id}:
    delete:
      description: >-
        Soft-deletes an Open-Finance data-aggregator (Pluggy/Belvo) connection
        by id, freeing its config name for reuse. A non-aggregator connection id
        returns 404.
      operationId: deleteAggregatorConnection
      parameters:
        - description: Opaque aggregator connection id
          in: path
          name: id
          required: true
          schema:
            description: Opaque aggregator connection id
            type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Delete aggregator connection
      tags:
        - Discovery
    get:
      description: >-
        Returns a single Open-Finance data-aggregator (Pluggy/Belvo) connection
        by id. The result is secret-free by construction: no credential material
        (clientId/secret/ciphertext) is ever returned. A non-aggregator
        connection id returns 404.
      operationId: getAggregatorConnection
      parameters:
        - description: Opaque aggregator connection id
          in: path
          name: id
          required: true
          schema:
            description: Opaque aggregator connection id
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatorConnectionResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Get aggregator connection
      tags:
        - Discovery
    put:
      description: >-
        Edits an existing Open-Finance data-aggregator (Pluggy/Belvo) connection
        by id so a mistyped baseUrl is not permanent. The vendor is immutable.
        clientId/secret are optional: supply both to rotate the sealed
        credential, or omit both to leave the stored secret intact. The supplied
        credential is sealed before persistence and is never returned. A
        non-aggregator connection id returns 404.
      operationId: updateAggregatorConnection
      parameters:
        - description: Opaque aggregator connection id
          in: path
          name: id
          required: true
          schema:
            description: Opaque aggregator connection id
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAggregatorConnectionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatorConnectionResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Update aggregator connection
      tags:
        - Discovery
  /v1/discovery/connector-types:
    get:
      description: >-
        Returns the connector types the engine registry has actually registered
        for this deployment, each tagged with a backend-derived category
        ('database' or 'rest'). The list reflects the live registry — only the
        connectors registered at boot appear, with no static enum of all
        possible types. Aggregator-vendor types (Pluggy/Belvo) are excluded —
        they are provisioned through the aggregator-connections surface.
      operationId: listDiscoveryConnectorTypes
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorTypeListResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List connector types
      tags:
        - Discovery
  /v1/discovery/webhooks/tokens:
    post:
      description: >-
        Mints a webhook token bound to an existing aggregator connection and
        returns the raw token plus its provider-facing webhook URL ONCE. Only
        the token's SHA-256 hash is stored.
      operationId: mintAggregatorWebhookToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MintRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MintResponse'
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Mint an aggregator webhook token
      tags:
        - Discovery
  /v1/discovery/webhooks/{provider}/{webhookToken}:
    post:
      description: >-
        Receives a Pluggy/Belvo aggregator webhook and asynchronously pulls the
        signaled data into the ingestion pipeline. This route carries no
        operator JWT. It is authenticated by an opaque token in the URL path
        (resolved to a tenant binding server-side, never claimed) PLUS a
        per-provider source check: a valid HMAC-SHA256 of the raw body in the
        X-Webhook-Signature header, OR membership in the provider's source-IP
        allowlist. Both layers fail closed; the tenant is derived solely from
        the resolved token binding.
      operationId: receiveAggregatorWebhook
      parameters:
        - description: Aggregator provider the token was minted for (pluggy or belvo)
          in: path
          name: provider
          required: true
          schema:
            description: Aggregator provider the token was minted for (pluggy or belvo)
            examples:
              - pluggy
            type: string
        - description: >-
            Opaque webhook token minted for the connection; hashed and resolved
            to a tenant binding server-side
          in: path
          name: webhookToken
          required: true
          schema:
            description: >-
              Opaque webhook token minted for the connection; hashed and
              resolved to a tenant binding server-side
            type: string
        - description: >-
            Hex HMAC-SHA256 of the raw body for signing providers; omitted by
            IP-allowlist providers
          in: header
          name: X-Webhook-Signature
          schema:
            description: >-
              Hex HMAC-SHA256 of the raw body for signing providers; omitted by
              IP-allowlist providers
            type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              contentMediaType: application/octet-stream
              format: binary
              type: string
        required: true
      responses:
        '202':
          description: Accepted
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - {}
        - WebhookSignature: []
      summary: Receive an aggregator webhook
      tags:
        - Discovery
  /v1/disputes/{disputeId}/evidence/upload:
    post:
      description: >-
        Streams an evidence file (pdf, png, jpeg, or csv) to tenant-scoped
        object storage and records the resulting object key on the dispute as a
        new evidence item. The comment arrives as a query parameter and the file
        bytes as the request body. The tenant is resolved from the JWT and the
        dispute from the path — never from the body. Fails closed (503) when
        object storage is not configured; rejects oversize bodies (413) and
        unsupported content types (415).
      operationId: uploadEvidence
      parameters:
        - description: Dispute ID (UUID)
          in: path
          name: disputeId
          required: true
          schema:
            description: Dispute ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440001
            format: uuid
            type: string
        - description: Comment describing the uploaded evidence
          explode: false
          in: query
          name: comment
          schema:
            description: Comment describing the uploaded evidence
            examples:
              - Bank statement showing correct amount
            maxLength: 1000
            minLength: 1
            type: string
        - description: >-
            Evidence media type: application/pdf, image/png, image/jpeg, or
            text/csv
          in: header
          name: Content-Type
          schema:
            description: >-
              Evidence media type: application/pdf, image/png, image/jpeg, or
              text/csv
            examples:
              - application/pdf
            type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              contentMediaType: application/octet-stream
              format: binary
              type: string
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisputeResponse'
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Upload an evidence file to a dispute
      tags:
        - Exception
  /v1/exceptions/callbacks/credentials:
    get:
      description: >-
        Lists the caller tenant's callback credentials (live and revoked),
        newest first. Returns metadata only — never the token or its hash.
      operationId: listCallbackCredentials
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List callback credentials
      tags:
        - Exception
    post:
      description: >-
        Mints an opaque bearer token bound to the caller's tenant for
        authenticating inbound external-system exception callbacks, and returns
        the raw token ONCE. Only the token's SHA-256 hash is stored server-side.
      operationId: mintCallbackCredential
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MintCredentialRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialSecretResponse'
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Mint a callback credential
      tags:
        - Exception
  /v1/exceptions/callbacks/credentials/{credentialId}:
    delete:
      description: >-
        Revokes a callback credential so it can no longer authenticate inbound
        callbacks. Revocation is terminal and append-only audited.
      operationId: revokeCallbackCredential
      parameters:
        - description: Id of the credential to revoke
          in: path
          name: credentialId
          required: true
          schema:
            description: Id of the credential to revoke
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Revoke a callback credential
      tags:
        - Exception
  /v1/exceptions/callbacks/credentials/{credentialId}/rotate:
    post:
      description: >-
        Atomically supersedes a live callback credential with a freshly minted
        one (same label) and returns the new raw token ONCE. The old credential
        is revoked in the same transaction.
      operationId: rotateCallbackCredential
      parameters:
        - description: Id of the live credential to rotate
          in: path
          name: credentialId
          required: true
          schema:
            description: Id of the live credential to rotate
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialSecretResponse'
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Rotate a callback credential
      tags:
        - Exception
  /v1/exceptions/ids:
    get:
      description: >-
        Resolves the ids of every exception matching the SAME filter as GET
        /v1/exceptions (status, severity, contextId, reason, assigned_to,
        external_system, search, date_from, date_to, min_age_days), up to a cap
        of 10000, for the bulk "select all matching" path. The response carries
        the filtered total and a truncated flag; the client chunks the returned
        ids into the capped bulk-action calls. No pagination/sort: it returns
        the whole filtered set (capped).
      operationId: selectExceptionIDs
      parameters:
        - description: >-
            Filter by reconciliation context ID (UUID, verified against the
            tenant; 404 when unknown)
          explode: false
          in: query
          name: contextId
          schema:
            description: >-
              Filter by reconciliation context ID (UUID, verified against the
              tenant; 404 when unknown)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - description: Filter by status
          explode: false
          in: query
          name: status
          schema:
            description: Filter by status
            enum:
              - OPEN
              - ASSIGNED
              - RESOLVED
            type: string
        - description: Filter by severity
          explode: false
          in: query
          name: severity
          schema:
            description: Filter by severity
            enum:
              - LOW
              - MEDIUM
              - HIGH
              - CRITICAL
            type: string
        - description: Filter by exception reason
          explode: false
          in: query
          name: reason
          schema:
            description: Filter by exception reason
            enum:
              - UNMATCHED
              - FX_RATE_UNAVAILABLE
              - MISSING_BASE_AMOUNT
              - MISSING_BASE_CURRENCY
              - SPLIT_INCOMPLETE
              - VALIDATION_FAILED
              - SOURCE_MISMATCH
              - DUPLICATE_TRANSACTION
              - FEE_VARIANCE
              - FEE_DATA_MISSING
              - FEE_CURRENCY_MISMATCH
              - FX_RATE_VARIANCE
              - AGED_BREAK
              - OVER_SETTLED
            type: string
        - description: Filter by assigned user
          explode: false
          in: query
          name: assigned_to
          schema:
            description: Filter by assigned user
            examples:
              - user@example.com
            type: string
        - description: Filter by external system
          explode: false
          in: query
          name: external_system
          schema:
            description: Filter by external system
            examples:
              - JIRA
            type: string
        - description: >-
            Free-text search across transaction id, reason, and external issue
            id (case-insensitive substring match)
          explode: false
          in: query
          name: search
          schema:
            description: >-
              Free-text search across transaction id, reason, and external issue
              id (case-insensitive substring match)
            examples:
              - .inf
            type: string
        - description: >-
            Filter from date, inclusive lower bound. Accepts an RFC 3339
            timestamp or a bare date (YYYY-MM-DD); a bare date is taken at
            00:00:00 UTC
          explode: false
          in: query
          name: date_from
          schema:
            description: >-
              Filter from date, inclusive lower bound. Accepts an RFC 3339
              timestamp or a bare date (YYYY-MM-DD); a bare date is taken at
              00:00:00 UTC
            examples:
              - '2025-01-01T00:00:00Z'
            type: string
        - description: >-
            Filter to date, inclusive upper bound. Accepts an RFC 3339 timestamp
            or a bare date (YYYY-MM-DD); a bare date covers the whole day
            through 23:59:59.999999999 UTC
          explode: false
          in: query
          name: date_to
          schema:
            description: >-
              Filter to date, inclusive upper bound. Accepts an RFC 3339
              timestamp or a bare date (YYYY-MM-DD); a bare date covers the
              whole day through 23:59:59.999999999 UTC
            examples:
              - '2025-01-31T23:59:59Z'
            type: string
        - description: >-
            Filter to exceptions at least this many days old (by created_at). 0
            (default) disables the filter.
          explode: false
          in: query
          name: min_age_days
          schema:
            description: >-
              Filter to exceptions at least this many days old (by created_at).
              0 (default) disables the filter.
            examples:
              - 30
            format: int64
            maximum: 3650
            minimum: 0
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelectExceptionIDsResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Select exception ids by filter
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/assign:
    post:
      description: >-
        Assigns a single exception to a user. Mirrors the bulk-assign auth and
        validation but acts on exactly one exception addressed by path. Returns
        the updated exception.
      operationId: assignException
      parameters:
        - description: Exception ID (UUID)
          in: path
          name: exceptionId
          required: true
          schema:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignExceptionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Assign an exception
      tags:
        - Exception
  /v1/exceptions/{exceptionId}/resolve:
    post:
      description: >-
        Resolves a single exception with a resolution and optional reason.
        Mirrors the bulk-resolve auth and validation but acts on exactly one
        exception addressed by path. Returns the updated exception.
      operationId: resolveException
      parameters:
        - description: Exception ID (UUID)
          in: path
          name: exceptionId
          required: true
          schema:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveExceptionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Resolve an exception
      tags:
        - Exception
  /v1/governance/actor-mappings:
    get:
      description: >-
        Lists actor mappings by actor ID with optional actor ID prefix
        filtering. Does not return display name or email.
      operationId: listActorMappings
      parameters:
        - description: Actor ID prefix
          explode: false
          in: query
          name: actorId
          schema:
            description: Actor ID prefix
            type: string
        - description: Actor ID cursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Actor ID cursor
            type: string
        - description: Page size (default 25, max 100)
          explode: false
          in: query
          name: limit
          schema:
            description: Page size (default 25, max 100)
            format: int64
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActorMappingListResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List actor mappings
      tags:
        - Governance
  /v1/governance/audit-logs/verify:
    get:
      description: >-
        Re-verifies the calling tenant's tamper-evident audit hash chain and
        returns a structured verdict (intact, verified count, and the first
        broken tenant_seq when a break is found). The check is strictly
        read-only: it recomputes nothing into storage and never mutates an audit
        record. Use the optional maxRecords query parameter to bound how many
        records are inspected.
      operationId: verifyAuditLogChain
      parameters:
        - description: >-
            Maximum number of records to inspect; clamped to the server bound.
            Omit to use the default bound.
          explode: false
          in: query
          name: maxRecords
          schema:
            description: >-
              Maximum number of records to inspect; clamped to the server bound.
              Omit to use the default bound.
            format: int64
            maximum: 10000
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditChainVerificationResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Verify audit log chain integrity
      tags:
        - Governance
  /v1/imports/contexts/{contextId}/extraction-reviews:
    get:
      description: >-
        Cursor-paginated list of extraction reviews for a context, optionally
        filtered by lifecycle status (e.g. PENDING_REVIEW for the queue). Tenant
        from the JWT, context from the path. Reads already-stored config-only
        candidates; it does not egress anything.
      operationId: listExtractionReviews
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Filter by status
          explode: false
          in: query
          name: status
          schema:
            description: Filter by status
            enum:
              - PENDING_REVIEW
              - APPROVED
              - REJECTED
            type: string
        - description: Page size
          explode: false
          in: query
          name: limit
          schema:
            description: Page size
            format: int64
            maximum: 200
            minimum: 1
            type: integer
        - description: Opaque pagination cursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionReviewListResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List AI extraction reviews (the human-review queue)
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}:
    get:
      description: >-
        Returns one extraction review with its candidates, provenance, and
        lifecycle. Tenant from the JWT, context from the path.
      operationId: getExtractionReview
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Review ID
          in: path
          name: reviewId
          required: true
          schema:
            description: Review ID
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionReviewResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Get a single AI extraction review
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}/approve:
    post:
      description: >-
        Approves a PENDING_REVIEW review and runs the SINGLE deterministic
        handoff into the normal ingestion pipeline (dedup + outbox +
        match-trigger), linking the resulting job to the review. This is the
        ONLY path from an AI candidate to a reconciled transaction, and it runs
        only on explicit human approval. The approving principal is the reviewer
        (audit attribution). Tenant from the JWT, context from the path.
      operationId: approveExtractionReview
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Review ID
          in: path
          name: reviewId
          required: true
          schema:
            description: Review ID
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApproveExtractionResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Approve an AI extraction review (ingest the candidates)
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}/reject:
    post:
      description: >-
        Rejects a PENDING_REVIEW review and discards its candidates — nothing is
        ingested or reconciled. The rejecting principal is recorded for audit.
        Tenant from the JWT, context from the path.
      operationId: rejectExtractionReview
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Review ID
          in: path
          name: reviewId
          required: true
          schema:
            description: Review ID
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectExtractionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionReviewResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Reject an AI extraction review (discard the candidates)
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/jobs/{jobId}/errors:
    get:
      description: >-
        Returns the stored per-row parse/normalization errors for an ingestion
        job (capped at 100 per job), with the uncapped failure total and
        truncation accounting. Lets clients explain failed or partially-failed
        imports.
      operationId: listIngestionJobErrors
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Job ID
          in: path
          name: jobId
          required: true
          schema:
            description: Job ID
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListJobErrorsResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List per-row import errors for a job
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/sources/{sourceId}/extract-document:
    post:
      description: >-
        Stores the uploaded source document tenant-scoped, runs deterministic +
        AI extraction, and enqueues the resulting transaction CANDIDATES in a
        human-review queue. AI output is NEVER authoritative: no transaction is
        reconciled until a human approves the review. The lane is gated by a
        global kill-switch AND a per-tenant opt-in (fail-closed: a non-opted-in
        tenant gets 403). The tenant is resolved from the JWT and the
        context/source from the path — never from the body.
      operationId: extractDocument
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
      requestBody:
        content:
          application/pdf:
            schema:
              contentMediaType: application/octet-stream
              format: binary
              type: string
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractDocumentResponse'
          description: Accepted
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Enqueue a document for AI extraction (human-review required)
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/sources/{sourceId}/fetch:
    post:
      description: >-
        Lists every object matching the supplied transport coordinates (SFTP
        today) and streams each into the trusted-content ingestion pipeline
        (dedup + outbox + match-trigger), returning a per-file outcome in fetch
        order. The tenant is resolved from the JWT and the context/source from
        the path — NEVER from the body. The body carries connection coordinates
        plus an OPAQUE credential reference, never a secret. A transport-level
        fetch failure (the external endpoint is unreachable or rejects the
        credential) returns 503; per-file intake failures are reported in the
        response body without failing the batch.
      operationId: fetchTrigger
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchTriggerRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchTriggerResponse'
          description: Accepted
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Trigger a manual fetch-and-ingest from an external transport
      tags:
        - Ingestion
  /v1/imports/contexts/{contextId}/sources/{sourceId}/mapping-proposal:
    post:
      description: >-
        Inspects a representative sample of a source file and returns a
        CONFIG-ONLY mapping/dialect proposal (column→canonical-key suggestions,
        dialect, per-field confidence and rationale). It is ADVISORY and
        side-effect-free: producing a proposal PERSISTS NOTHING. The operator
        reviews the proposal and confirms it through the EXISTING field-map
        declaration path. The tenant is resolved from the JWT and the
        context/source from the path — never from the body. The response never
        carries parsed values, amounts, or transactions.
      operationId: proposeMapping
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Source ID
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProposeMappingRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingProposalResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Propose a config-only field-map/dialect mapping for a source sample
      tags:
        - Ingestion
  /v1/imports/formats:
    get:
      description: >-
        Returns the read-only catalog of formats the ingestion engine can parse,
        namespaced region -> family -> variant. The catalog is global-first and
        static (built-in parsers carry no tenant), so the response is identical
        for every authenticated caller. No path, query, or body parameters — the
        tenant is irrelevant to the built-in catalog.
      operationId: browseFormatCatalog
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormatCatalogResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Browse the supported format catalog
      tags:
        - Ingestion
  /v1/imports/formats/templates:
    get:
      description: >-
        Returns every active per-tenant fixed-width layout template. The list is
        unpaginated: layout templates are bounded operator config. Tenant from
        the JWT; never the body.
      operationId: listLayoutTemplates
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLayoutTemplatesResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List operator fixed-width layout templates
      tags:
        - Ingestion
    post:
      description: >-
        Validates and stores a per-tenant fixed-width layout template
        (region/family/variant-namespaced). The layout is run through the
        well-formedness gate BEFORE storage: overrun, overlap, missing-required,
        zero-field, or a mis-marked money column (money MUST be kind=decimal)
        rejects with 422 and the template is never stored. An approved template
        is resolved by the parse path as an additive layout source. Tenant from
        the JWT; never the body.
      operationId: submitLayoutTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLayoutTemplateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayoutTemplateResponse'
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Submit an operator fixed-width layout template
      tags:
        - Ingestion
  /v1/imports/formats/templates/{templateId}:
    delete:
      description: >-
        Soft-deletes one active per-tenant fixed-width layout template by its
        id, freeing its format/variant key for reuse. Returns 404 when no active
        template matches. Tenant from the JWT; never the body.
      operationId: deleteLayoutTemplate
      parameters:
        - description: Layout template ID
          in: path
          name: templateId
          required: true
          schema:
            description: Layout template ID
            format: uuid
            type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Delete an operator fixed-width layout template
      tags:
        - Ingestion
    get:
      description: >-
        Retrieves one active per-tenant fixed-width layout template by its id.
        Returns 404 when no active template matches. Tenant from the JWT; never
        the body.
      operationId: getLayoutTemplate
      parameters:
        - description: Layout template ID
          in: path
          name: templateId
          required: true
          schema:
            description: Layout template ID
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayoutTemplateResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Get an operator fixed-width layout template
      tags:
        - Ingestion
    put:
      description: >-
        Fully replaces a stored per-tenant fixed-width layout template
        (records/fields/discriminator/recordWidths/requiredFields) by its id — a
        PUT full replace, not a sparse patch, since the byte-range invariants
        are whole-layout properties. The replacement is run through the SAME
        well-formedness gate the submission path enforces BEFORE storage:
        overrun, overlap, missing-required, zero-field, or a mis-marked money
        column (money MUST be kind=decimal) rejects with 422 and the stored
        template is left unchanged. Returns 404 when no active template matches,
        409 when the new format key collides with another active template.
        Tenant from the JWT; never the body.
      operationId: updateLayoutTemplate
      parameters:
        - description: Layout template ID
          in: path
          name: templateId
          required: true
          schema:
            description: Layout template ID
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLayoutTemplateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayoutTemplateResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Replace an operator fixed-width layout template
      tags:
        - Ingestion
  /v1/matching/candidates:
    get:
      description: >-
        Returns a ranked list of opposite-side unmatched transactions the engine
        considers plausible counterparts for the target transaction, each with a
        confidence score, the rule that drove it, a per-component rationale (the
        "why"), and amount/date deltas. Powers the exception-resolution and
        manual-match candidate pickers. Scope: proposals are scored by the
        deterministic rule engine over raw transaction amounts and do NOT apply
        run-time fee normalization or the FX-variance band; only 1:1 pairwise
        counterparts are returned.
      operationId: listMatchCandidates
      parameters:
        - description: Context ID the transaction belongs to
          explode: false
          in: query
          name: contextId
          required: true
          schema:
            description: Context ID the transaction belongs to
            format: uuid
            type: string
        - description: >-
            Target transaction to find counterparts for. For an exception,
            resolve its transaction id first, then pass it here.
          explode: false
          in: query
          name: transactionId
          required: true
          schema:
            description: >-
              Target transaction to find counterparts for. For an exception,
              resolve its transaction id first, then pass it here.
            format: uuid
            type: string
        - description: Maximum number of ranked proposals to return
          explode: false
          in: query
          name: limit
          schema:
            default: 50
            description: Maximum number of ranked proposals to return
            format: int64
            maximum: 200
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateProposalsResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List match candidates for a transaction
      tags:
        - Matching
  /v1/matching/contexts/{contextId}/open-items:
    get:
      description: >-
        Returns a cursor-paginated list of open-item residual ledger entries for
        a reconciliation context — the carried, partially-filled, and aged
        obligations the context carries forward across match runs. These are
        structurally distinct from never-matched (UNMATCHED) transactions.
        Optionally narrowed by lifecycle status. The listing is readable
        regardless of context status.
      operationId: listOpenItems
      parameters:
        - description: Reconciliation context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Reconciliation context ID
            format: uuid
            type: string
        - description: Filter by open-item lifecycle status
          explode: false
          in: query
          name: status
          schema:
            description: Filter by open-item lifecycle status
            enum:
              - OPEN
              - PARTIALLY_CLEARED
              - CLEARED
              - AGED
            type: string
        - description: Maximum number of records to return
          explode: false
          in: query
          name: limit
          schema:
            default: 20
            description: Maximum number of records to return
            format: int64
            maximum: 200
            minimum: 1
            type: integer
        - description: Opaque pagination cursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor
            type: string
        - description: >-
            Field to sort by. Defaults to id (stable insertion order). ageDays
            sorts by aging anchor (oldest residuals first when descending)
          explode: false
          in: query
          name: sort_by
          schema:
            description: >-
              Field to sort by. Defaults to id (stable insertion order). ageDays
              sorts by aging anchor (oldest residuals first when descending)
            enum:
              - ageDays
              - runningBalance
              - obligationDate
            type: string
        - description: Sort order
          explode: false
          in: query
          name: sort_order
          schema:
            description: Sort order
            enum:
              - asc
              - desc
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOpenItemsResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List open items
      tags:
        - Matching
  /v1/matching/contexts/{contextId}/rule-suggestions:
    get:
      description: >-
        Cursor-paginated list of rule suggestions for a context, optionally
        filtered by status (e.g. PENDING_REVIEW). Reads stored config-only
        candidates; egresses nothing. Tenant from the JWT, context from the
        path.
      operationId: listMatchRuleSuggestions
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Filter by status
          explode: false
          in: query
          name: status
          schema:
            description: Filter by status
            enum:
              - PENDING_REVIEW
              - APPROVED
              - REJECTED
            type: string
        - description: Page size
          explode: false
          in: query
          name: limit
          schema:
            description: Page size
            format: int64
            maximum: 200
            minimum: 1
            type: integer
        - description: Opaque pagination cursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleSuggestionListResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: List AI match-rule suggestions (the human-review queue)
      tags:
        - Matching
    post:
      description: >-
        Builds AGGREGATE, privacy-safe history features for the context, asks
        the AI advisor for config-only candidate rules, and enqueues each
        surviving candidate in a human-review queue. AI output is NEVER
        authoritative: producing a suggestion CREATES NO rule. A rule is created
        only when a human APPROVES a suggestion. The lane is gated by a global
        advisor kill-switch AND a per-tenant opt-in (fail-closed: a non-opted-in
        tenant gets 403). Tenant from the JWT, context from the path. The egress
        payload is aggregates only — no raw transaction, money, or PII.
      operationId: suggestMatchRules
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuggestRulesResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Produce AI match-rule suggestions (human-review required)
      tags:
        - Matching
  /v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/approve:
    post:
      description: >-
        Approves a PENDING_REVIEW suggestion and creates the match rule through
        the deterministic configuration write path. This is the ONLY path from
        an AI suggestion to an active match rule, and it runs only on explicit
        human approval. The approving principal is recorded for audit. Tenant
        from the JWT, context from the path.
      operationId: approveMatchRuleSuggestion
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Suggestion ID
          in: path
          name: suggestionId
          required: true
          schema:
            description: Suggestion ID
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApproveRuleSuggestionResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Approve an AI match-rule suggestion (create the rule)
      tags:
        - Matching
  /v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/reject:
    post:
      description: >-
        Rejects a PENDING_REVIEW suggestion — nothing is created. The rejecting
        principal is recorded for audit. Tenant from the JWT, context from the
        path.
      operationId: rejectMatchRuleSuggestion
      parameters:
        - description: Context ID
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - description: Suggestion ID
          in: path
          name: suggestionId
          required: true
          schema:
            description: Suggestion ID
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectRuleSuggestionRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleSuggestionResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Reject an AI match-rule suggestion (discard it)
      tags:
        - Matching
  /v1/matching/simulate:
    post:
      description: >-
        Previews how a single rule — an existing configured rule (ruleId) OR an
        inline candidate rule (rule) — would match a context's unmatched
        transactions, WITHOUT committing anything. Returns the number of 1:1
        groups the rule would form, a bounded sample of would-match pairs (each
        with a confidence score, a per-component rationale (the "why"), and
        matched composite keys), and the per-side unmatched counts. Powers the
        rule-authoring "will this rule actually match?" preview. Scope: scored
        by the deterministic rule engine over raw transaction amounts; it does
        NOT apply run-time fee normalization or the FX-variance band, and
        previews only 1:1 pairwise grouping (no 1:N/N:M allocation). Nothing is
        persisted; the tenant is taken from the JWT, never the body.
      operationId: simulateMatchRule
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateMatchRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulateMatchResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
          description: Error
      security:
        - BearerAuth: []
      summary: Simulate a match rule against a context (read-only dry run)
      tags:
        - Matching
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Bearer token authentication (format: "Bearer {token}")'
    WebhookSignature:
      description: >-
        Hex HMAC-SHA256 of the raw request body, proving an inbound aggregator
        webhook originated from the configured provider.
      in: header
      name: X-Webhook-Signature
      type: apiKey
  parameters:
    XIdempotencyKey:
      name: X-Idempotency-Key
      in: header
      required: false
      description: >-
        Optional idempotency key for safe retries. Also accepts
        `Idempotency-Key` as an alternative header name. If the same key is sent
        again and the original request was already processed, the cached
        response is returned with `X-Idempotency-Replayed: true`.


        See [Retries and idempotency](/en/reference/retries-idempotency) for
        details.
      schema:
        type: string
  headers:
    XIdempotencyReplayed:
      description: >-
        Indicates whether this response was served from the idempotency cache.
        When `true`, the response is a replay of the original request with the
        same idempotency key.


        See [Retries and idempotency](/en/reference/retries-idempotency) for
        details.
      schema:
        type: boolean
      example: false
  schemas:
    MatchRuleResponse:
      description: Matching rule within a reconciliation context
      properties:
        config:
          additionalProperties: {}
          description: Rule configuration
          type: object
        contextId:
          description: Context ID this rule belongs to
          example: 019c96a0-10a0-72d2-9fb0-2b7de8093182
          type: string
        createdAt:
          description: Creation timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        id:
          description: Unique identifier for the rule
          example: 019c96a0-1071-7a0d-9916-a831221de252
          type: string
        priority:
          description: Execution priority (lower = higher priority)
          example: 1
          maximum: 1000
          minimum: 1
          type: integer
        type:
          description: Type of matching rule
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
          example: EXACT
          type: string
        updatedAt:
          description: Last update timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
      type: object
    ReconciliationContextResponse:
      description: Configuration context for matching rules
      properties:
        id:
          description: Unique identifier for the context
          example: 019c96a0-10a0-72d2-9fb0-2b7de8093182
          type: string
        tenantId:
          description: Tenant ID this context belongs to
          example: 019c96a0-0a98-7287-9a31-786e0809c769
          type: string
        name:
          description: Name of the reconciliation context
          example: Bank Reconciliation Q1
          type: string
        type:
          description: Reconciliation topology type
          enum:
            - '1:1'
            - 1:N
            - N:M
          example: '1:1'
          type: string
        interval:
          description: Execution interval
          example: daily
          type: string
        status:
          description: Current status of the context
          enum:
            - DRAFT
            - ACTIVE
            - PAUSED
            - ARCHIVED
          example: ACTIVE
          type: string
        feeToleranceAbs:
          description: Absolute fee tolerance amount
          example: '0.50'
          type: string
        feeTolerancePct:
          description: Percentage fee tolerance
          example: '0.01'
          type: string
        feeNormalization:
          description: Fee normalization mode
          enum:
            - NET
            - GROSS
          example: NET
          type: string
        autoMatchOnUpload:
          description: Whether matching triggers automatically after file upload
          example: false
          type: boolean
        createdAt:
          description: Creation timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        updatedAt:
          description: Last update timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
      type: object
    SourceWithFieldMapStatusResponse:
      description: Source with field map availability information
      properties:
        id:
          description: Unique identifier for the source
          example: 019c96a0-108c-7a74-8e31-3789daffe1ed
          type: string
        contextId:
          description: Context ID this source belongs to
          example: 019c96a0-10a0-72d2-9fb0-2b7de8093182
          type: string
        name:
          description: Name of the source
          example: Primary Bank Account
          type: string
        type:
          description: Type of the source
          enum:
            - LEDGER
            - BANK
            - GATEWAY
            - CUSTOM
          example: BANK
          type: string
        config:
          additionalProperties: {}
          description: Source configuration
          type: object
        hasFieldMaps:
          description: Indicates if field maps are configured for this source
          example: true
          type: boolean
        createdAt:
          description: Creation timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        updatedAt:
          description: Last update timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
      type: object
    CreateFieldMapRequest:
      properties:
        mapping:
          type: object
      required:
        - mapping
      type: object
    CreateMatchRuleRequest:
      properties:
        config:
          type: object
        priority:
          example: 1
          maximum: 1000
          minimum: 1
          type: integer
        type:
          allOf:
            - $ref: '#/components/schemas/RuleType'
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
          example: EXACT
      required:
        - priority
        - type
      type: object
    CreateContextRequest:
      properties:
        name:
          example: Bank Reconciliation Q1
          maxLength: 100
          minLength: 1
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/ContextType'
          enum:
            - '1:1'
            - 1:N
            - N:M
          example: '1:1'
        interval:
          example: daily
          maxLength: 100
          minLength: 1
          type: string
        feeToleranceAbs:
          description: Absolute fee tolerance amount
          example: '0.01'
          type: string
        feeTolerancePct:
          description: Percentage fee tolerance
          example: '0.5'
          type: string
        feeNormalization:
          description: Fee normalization mode
          enum:
            - NET
            - GROSS
          example: NET
          type: string
        autoMatchOnUpload:
          description: Whether to trigger matching automatically after file upload
          example: false
          type: boolean
        sources:
          description: Optional list of sources to create inline with the context
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/CreateContextSourceRequest'
        rules:
          description: Optional list of match rules to create inline with the context
          type: array
          maxItems: 50
          items:
            type: object
            required:
              - priority
              - type
            properties:
              priority:
                description: Rule priority (lower number = higher priority)
                example: 1
                minimum: 1
                maximum: 1000
                type: integer
              type:
                description: Matching strategy type
                enum:
                  - EXACT
                  - TOLERANCE
                  - DATE_LAG
                example: EXACT
                type: string
              config:
                description: Rule-specific configuration
                additionalProperties: {}
                type: object
      required:
        - name
        - type
        - interval
      type: object
    CreateContextSourceRequest:
      description: Request payload for creating a source inline with a context
      type: object
      properties:
        name:
          description: Source name
          example: Primary Bank Account
          maxLength: 50
          minLength: 1
          type: string
        type:
          description: Source type
          enum:
            - LEDGER
            - BANK
            - GATEWAY
            - CUSTOM
            - FETCHER
          example: BANK
          type: string
        side:
          description: Which side of the reconciliation this source represents
          enum:
            - LEFT
            - RIGHT
          example: LEFT
          type: string
        config:
          description: Source-specific configuration
          additionalProperties: {}
          type: object
        mapping:
          description: Optional field mapping for this source
          additionalProperties: {}
          type: object
      required:
        - name
        - side
        - type
    CreateSourceRequest:
      properties:
        name:
          example: Primary Bank Account
          maxLength: 50
          minLength: 1
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/SourceType'
          enum:
            - LEDGER
            - BANK
            - GATEWAY
            - CUSTOM
            - FETCHER
          example: BANK
        side:
          description: Side of the reconciliation this source feeds
          enum:
            - LEFT
            - RIGHT
          example: LEFT
          type: string
        config:
          additionalProperties: {}
          type: object
      required:
        - name
        - side
        - type
      type: object
    FieldMapResponse:
      properties:
        contextId:
          type: string
        createdAt:
          type: string
        id:
          type: string
        mapping:
          additionalProperties: {}
          type: object
        sourceId:
          type: string
        updatedAt:
          type: string
        version:
          type: integer
      type: object
    ReconciliationSourceResponse:
      properties:
        id:
          type: string
        contextId:
          type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/SourceType'
        side:
          description: Side of the reconciliation this source feeds
          enum:
            - LEFT
            - RIGHT
          type: string
        config:
          additionalProperties: {}
          type: object
        createdAt:
          type: string
        updatedAt:
          type: string
      type: object
    UpdateFieldMapRequest:
      properties:
        mapping:
          type: object
      type: object
    UpdateMatchRuleRequest:
      properties:
        config:
          type: object
        priority:
          example: 2
          maximum: 1000
          minimum: 1
          type: integer
        type:
          allOf:
            - $ref: '#/components/schemas/RuleType'
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
          example: TOLERANCE
      type: object
    UpdateContextRequest:
      properties:
        name:
          example: Bank Reconciliation Q2
          maxLength: 100
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/ContextType'
          enum:
            - '1:1'
            - 1:N
            - N:M
          example: 1:N
        interval:
          example: weekly
          maxLength: 100
          type: string
        status:
          allOf:
            - $ref: '#/components/schemas/ContextStatus'
          enum:
            - DRAFT
            - ACTIVE
            - PAUSED
            - ARCHIVED
          example: ACTIVE
        feeToleranceAbs:
          description: Absolute fee tolerance amount
          example: '0.01'
          type: string
        feeTolerancePct:
          description: Percentage fee tolerance
          example: '0.5'
          type: string
        feeNormalization:
          description: Fee normalization mode
          enum:
            - NET
            - GROSS
          example: NET
          type: string
        autoMatchOnUpload:
          description: Whether to trigger matching automatically after file upload
          example: false
          type: boolean
      type: object
    UpdateSourceRequest:
      properties:
        name:
          example: Secondary Bank Account
          maxLength: 50
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/SourceType'
          enum:
            - LEDGER
            - BANK
            - GATEWAY
            - CUSTOM
            - FETCHER
          example: LEDGER
        side:
          description: Side of the reconciliation this source feeds
          enum:
            - LEFT
            - RIGHT
          example: RIGHT
          type: string
        config:
          additionalProperties: {}
          type: object
      type: object
    ContextStatus:
      description: Lifecycle status of a reconciliation context
      enum:
        - DRAFT
        - ACTIVE
        - PAUSED
        - ARCHIVED
      type: string
      x-enum-varnames:
        - ContextStatusDraft
        - ContextStatusActive
        - ContextStatusPaused
        - ContextStatusArchived
    ContextType:
      description: Reconciliation topology (cardinality between sources)
      enum:
        - '1:1'
        - 1:N
        - N:M
      type: string
      x-enum-varnames:
        - ContextTypeOneToOne
        - ContextTypeOneToMany
        - ContextTypeManyToMany
    SourceType:
      description: Category of data source for reconciliation
      enum:
        - LEDGER
        - BANK
        - GATEWAY
        - CUSTOM
        - FETCHER
      type: string
      x-enum-varnames:
        - SourceTypeLedger
        - SourceTypeBank
        - SourceTypeGateway
        - SourceTypeCustom
        - SourceTypeFetcher
    ApplicationOrder:
      description: Determines how multiple fee items compose within a schedule
      enum:
        - PARALLEL
        - CASCADING
      type: string
      x-enum-varnames:
        - ApplicationOrderParallel
        - ApplicationOrderCascading
    RoundingMode:
      description: Determines how intermediate fee calculations are rounded
      enum:
        - HALF_UP
        - BANKERS
        - FLOOR
        - CEIL
        - TRUNCATE
      type: string
      x-enum-varnames:
        - RoundingModeHalfUp
        - RoundingModeBankers
        - RoundingModeFloor
        - RoundingModeCeil
        - RoundingModeTruncate
    StructureType:
      description: Type of fee structure for a fee schedule item
      enum:
        - FLAT
        - PERCENTAGE
        - TIERED
      type: string
      x-enum-varnames:
        - StructureTypeFlat
        - StructureTypePercentage
        - StructureTypeTiered
    FeeScheduleResponse:
      description: Fee schedule with its fee items
      properties:
        id:
          description: Unique identifier for the fee schedule
          example: 019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b
          format: uuid
          type: string
        tenantId:
          description: Tenant that owns this fee schedule
          example: 019c96a0-0a98-7287-9a31-786e0809c769
          format: uuid
          type: string
        name:
          description: Display name for the fee schedule
          example: Card Processing - Visa
          maxLength: 100
          type: string
        currency:
          description: Currency code (ISO 4217)
          example: USD
          type: string
        applicationOrder:
          description: How multiple fee items compose
          example: PARALLEL
          allOf:
            - $ref: '#/components/schemas/ApplicationOrder'
        roundingScale:
          description: Number of decimal places for rounding
          example: 2
          type: integer
        roundingMode:
          description: Rounding method for intermediate calculations
          example: HALF_UP
          allOf:
            - $ref: '#/components/schemas/RoundingMode'
        items:
          description: Fee items in this schedule
          items:
            $ref: '#/components/schemas/FeeScheduleItemResponse'
          maxItems: 100
          type: array
        createdAt:
          description: Creation timestamp in RFC 3339 format
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
      type: object
    FeeScheduleItemResponse:
      description: A single fee item within a fee schedule
      properties:
        id:
          description: Unique identifier for the fee item
          example: 019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b
          format: uuid
          type: string
        name:
          description: Display name for the fee item
          example: interchange
          type: string
        priority:
          description: Execution priority (lower numbers run first)
          example: 1
          type: integer
        structureType:
          description: Type of fee structure
          example: PERCENTAGE
          allOf:
            - $ref: '#/components/schemas/StructureType'
        structure:
          description: Fee structure definition (varies by structureType)
          type: object
          additionalProperties: true
        createdAt:
          description: Creation timestamp in RFC 3339 format
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
      type: object
    CreateFeeScheduleRequest:
      description: Payload for creating a fee schedule
      properties:
        name:
          description: Display name for the fee schedule
          example: Card Processing - Visa
          maxLength: 100
          minLength: 1
          type: string
        currency:
          description: Currency code (ISO 4217)
          example: USD
          maxLength: 3
          type: string
        applicationOrder:
          description: How multiple fee items compose
          example: PARALLEL
          allOf:
            - $ref: '#/components/schemas/ApplicationOrder'
        roundingScale:
          description: Number of decimal places for rounding
          example: 2
          type: integer
        roundingMode:
          description: Rounding method for intermediate calculations
          example: HALF_UP
          allOf:
            - $ref: '#/components/schemas/RoundingMode'
        items:
          description: Fee items to include in this schedule
          items:
            $ref: '#/components/schemas/CreateFeeScheduleItemRequest'
          maxItems: 100
          minItems: 1
          type: array
      required:
        - name
        - currency
        - applicationOrder
        - items
      type: object
    CreateFeeScheduleItemRequest:
      description: Payload for creating a fee item within a schedule
      properties:
        name:
          description: Display name for the fee item
          example: interchange
          maxLength: 100
          type: string
        priority:
          description: Execution priority (lower numbers run first)
          example: 1
          type: integer
        structureType:
          description: Type of fee structure
          example: PERCENTAGE
          allOf:
            - $ref: '#/components/schemas/StructureType'
        structure:
          description: Fee structure definition (varies by structureType)
          type: object
          additionalProperties: true
      required:
        - name
        - structureType
        - structure
      type: object
    UpdateFeeScheduleRequest:
      description: Payload for updating a fee schedule
      properties:
        name:
          description: Updated display name
          example: Updated Schedule
          maxLength: 100
          type: string
        applicationOrder:
          description: Updated application order
          example: CASCADING
          allOf:
            - $ref: '#/components/schemas/ApplicationOrder'
        roundingScale:
          description: Updated number of decimal places
          example: 4
          type: integer
        roundingMode:
          description: Updated rounding method
          example: BANKERS
          allOf:
            - $ref: '#/components/schemas/RoundingMode'
      type: object
    SimulateFeeRequest:
      description: Payload for simulating fee calculation against a fee schedule
      properties:
        grossAmount:
          description: Gross transaction amount to simulate fees on
          example: '100.00'
          type: string
        currency:
          description: Currency code (ISO 4217)
          example: USD
          type: string
      required:
        - grossAmount
        - currency
      type: object
    SimulateFeeResponse:
      description: Result of a fee simulation
      properties:
        grossAmount:
          description: Original gross amount
          example: '100.00'
          type: string
        netAmount:
          description: Amount after fees are deducted
          example: '97.70'
          type: string
        totalFee:
          description: Total fee amount
          example: '2.30'
          type: string
        currency:
          description: Currency code (ISO 4217)
          example: USD
          type: string
        items:
          description: Breakdown of individual fee items
          items:
            $ref: '#/components/schemas/SimulateFeeItem'
          maxItems: 100
          type: array
      type: object
    SimulateFeeItem:
      description: A single fee item in a simulation result
      properties:
        name:
          description: Name of the fee item
          example: interchange
          type: string
        fee:
          description: Calculated fee amount
          example: '1.50'
          type: string
        baseUsed:
          description: Base amount used for this fee calculation
          example: '100.00'
          type: string
      type: object
    ListFeeSchedulesResponse:
      description: Paginated list of fee schedules
      properties:
        items:
          items:
            $ref: '#/components/schemas/FeeScheduleResponse'
          maxItems: 200
          type: array
        cursor:
          description: Cursor value to retrieve the next page of results
          example: eyJpZCI6IjAxOWM5NmEwLTJiMjAtNzEyMy05YTFiLTJjM2Q0ZTVmNmE3YiJ9
          type: string
      type: object
    FeeRuleResponse:
      description: >-
        A fee rule that maps transaction metadata to a fee schedule within a
        reconciliation context
      properties:
        id:
          description: Unique identifier for the fee rule
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        contextId:
          description: Reconciliation context this rule belongs to
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        feeScheduleId:
          description: Fee schedule applied when this rule matches
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        name:
          description: Display name for the fee rule
          example: BB Right-Side Rule
          type: string
        side:
          description: Which transaction side this rule applies to
          example: RIGHT
          enum:
            - LEFT
            - RIGHT
            - ANY
          type: string
        priority:
          description: >-
            Evaluation priority (lower numbers are evaluated first; LEFT, RIGHT,
            and ANY rules share the same priority space)
          example: 0
          type: integer
        predicates:
          description: Conditions that must all match for this rule to apply
          items:
            $ref: '#/components/schemas/FieldPredicateResponse'
          type: array
        createdAt:
          description: Creation timestamp in RFC 3339 format
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
      type: object
    ListFeeRulesResponse:
      description: List of fee rules for a reconciliation context
      properties:
        items:
          items:
            $ref: '#/components/schemas/FeeRuleResponse'
          type: array
      type: object
    CreateFeeRuleRequest:
      description: Request payload for creating a fee rule
      properties:
        feeScheduleId:
          description: The fee schedule to apply when this rule matches
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        name:
          description: Display name for the fee rule
          example: BB Right-Side Rule
          maxLength: 100
          minLength: 1
          type: string
        side:
          description: Which transaction side this rule applies to
          example: RIGHT
          enum:
            - LEFT
            - RIGHT
            - ANY
          type: string
        priority:
          description: >-
            Evaluation priority (must be unique within the context; LEFT, RIGHT,
            and ANY rules share the same priority space)
          example: 0
          minimum: 0
          type: integer
        predicates:
          description: Conditions that must all match for this rule to apply
          items:
            $ref: '#/components/schemas/FieldPredicateRequest'
          maxItems: 50
          type: array
      required:
        - feeScheduleId
        - name
        - side
      type: object
    UpdateFeeRuleRequest:
      description: Request payload for updating a fee rule
      properties:
        feeScheduleId:
          description: Updated fee schedule to apply when this rule matches
          type: string
        name:
          description: Updated display name for the fee rule
          example: Updated Rule
          maxLength: 100
          type: string
        side:
          description: Updated transaction side
          example: LEFT
          enum:
            - LEFT
            - RIGHT
            - ANY
          type: string
        priority:
          description: Updated evaluation priority (must remain unique within the context)
          minimum: 0
          type: integer
        predicates:
          description: Updated conditions for this rule
          items:
            $ref: '#/components/schemas/FieldPredicateRequest'
          maxItems: 50
          type: array
      type: object
    FieldPredicateRequest:
      description: A condition used to evaluate whether a fee rule applies to a transaction
      properties:
        field:
          description: Transaction field to evaluate
          example: institution
          maxLength: 255
          type: string
        operator:
          description: Comparison operator
          example: EQUALS
          enum:
            - EQUALS
            - IN
            - EXISTS
          type: string
        value:
          description: >-
            Single value to compare against (used with EQUALS and EXISTS
            operators)
          example: Banco do Brasil
          maxLength: 1024
          type: string
        values:
          description: List of values to compare against (used with IN operator)
          items:
            type: string
          maxItems: 100
          type: array
      required:
        - field
        - operator
      type: object
    FieldPredicateResponse:
      description: An evaluated condition within a fee rule
      properties:
        field:
          description: Transaction field being evaluated
          example: institution
          type: string
        operator:
          description: Comparison operator
          example: EQUALS
          enum:
            - EQUALS
            - IN
            - EXISTS
          type: string
        value:
          description: Single value being compared
          example: Banco do Brasil
          type: string
        values:
          description: List of values being compared
          items:
            type: string
          type: array
      type: object
    DiscoveryStatusResponse:
      description: Current status of the Fetcher integration
      properties:
        fetcherHealthy:
          description: Whether the Fetcher service is currently reachable and healthy
          example: true
          type: boolean
        connectionCount:
          description: Number of connections discovered from Fetcher
          example: 5
          type: integer
        lastSyncAt:
          description: >-
            Timestamp of the last successful sync with Fetcher in RFC 3339
            format
          example: '2025-01-15T10:30:00Z'
          type: string
      type: object
    ConnectionListResponse:
      description: List of discovered Fetcher connections
      properties:
        connections:
          description: Discovered connections
          items:
            $ref: '#/components/schemas/ConnectionResponse'
          type: array
      type: object
    ConnectionResponse:
      description: A discovered Fetcher database connection
      properties:
        id:
          description: Internal identifier for the connection
          type: string
        configName:
          description: Name of the Fetcher configuration that produced this connection
          type: string
        databaseType:
          description: Type of database (e.g. postgres, mysql)
          type: string
        status:
          description: Current connection status
          type: string
        schemaDiscovered:
          description: Whether the table schema has been discovered for this connection
          type: boolean
        lastSeenAt:
          description: Timestamp when this connection was last observed in Fetcher
          type: string
      type: object
    ConnectionSchemaResponse:
      description: Discovered table schemas for a connection
      properties:
        connectionId:
          description: Identifier of the connection these schemas belong to
          type: string
        tables:
          description: Discovered tables and their column definitions
          items:
            $ref: '#/components/schemas/SchemaTableResponse'
          type: array
      type: object
    SchemaTableResponse:
      description: A discovered table within a connection
      properties:
        tableName:
          description: Name of the table
          type: string
        columns:
          description: Columns in the table
          items:
            $ref: '#/components/schemas/SchemaColumnResponse'
          type: array
      type: object
    SchemaColumnResponse:
      description: A column within a discovered table
      properties:
        name:
          description: Column name
          type: string
        type:
          description: Column data type
          type: string
        nullable:
          description: Whether the column accepts null values
          type: boolean
      type: object
    TestConnectionResponse:
      description: Result of a connectivity test for a discovered connection
      properties:
        connectionId:
          description: Identifier of the connection that was tested
          type: string
        healthy:
          description: Whether the connection test succeeded
          example: true
          type: boolean
        latencyMs:
          description: Round-trip latency in milliseconds
          example: 42
          type: integer
        errorMessage:
          description: Error details when the test failed
          type: string
      type: object
    StartExtractionRequest:
      description: >-
        Request payload for starting a data extraction from a discovered
        connection
      properties:
        tables:
          description: Tables to extract data from, keyed by table name
          additionalProperties:
            $ref: '#/components/schemas/ExtractionTableRequest'
          type: object
        startDate:
          description: Start of the date range to extract (RFC 3339)
          type: string
        endDate:
          description: End of the date range to extract (RFC 3339)
          type: string
        filters:
          $ref: '#/components/schemas/ExtractionFilters'
      required:
        - tables
      type: object
    ExtractionTableRequest:
      description: Column selection for a single table in an extraction request
      properties:
        columns:
          description: Column names to include in the extraction
          items:
            type: string
          minItems: 1
          type: array
      required:
        - columns
      type: object
    ExtractionRequestResponse:
      description: An extraction request submitted to Fetcher
      properties:
        id:
          description: Internal identifier for the extraction request
          type: string
        connectionId:
          description: Connection this extraction was submitted to
          type: string
        status:
          description: Current lifecycle status of the extraction
          type: string
        ingestionJobId:
          description: Job identifier returned by Fetcher
          type: string
        startDate:
          description: Start of the extracted date range
          type: string
        endDate:
          description: End of the extracted date range
          type: string
        tables:
          description: Per-table extraction status
          additionalProperties:
            $ref: '#/components/schemas/ExtractionTableResponse'
          type: object
        filters:
          $ref: '#/components/schemas/ExtractionFilters'
        errorMessage:
          description: Error details if the extraction failed
          type: string
        createdAt:
          description: Timestamp when the extraction was requested
          type: string
        updatedAt:
          description: Timestamp of the last status update
          type: string
        bridgeAttempts:
          description: >-
            Number of times the Matcher bridge pipeline has attempted to
            retrieve and ingest this extraction
          example: 0
          type: integer
        bridgeLastError:
          description: Error class of the last bridge pipeline failure
          example: ''
          type: string
        bridgeLastErrorMessage:
          description: >-
            Appended-history error message from the bridge pipeline; primary
            failure stays at the head
          example: ''
          type: string
        bridgeFailedAt:
          description: >-
            Timestamp of the first terminal bridge failure; omitted when no
            failure has occurred
          format: date-time
          type:
            - string
            - 'null'
        custodyDeletedAt:
          description: >-
            Timestamp when the custody object was deleted; omitted when still
            held
          format: date-time
          type:
            - string
            - 'null'
      type: object
    ExtractionTableResponse:
      description: Extraction status for a single table
      properties:
        columns:
          description: Columns included in the extraction
          items:
            type: string
          type: array
      type: object
    ExtractionFilters:
      description: Optional row-level filters for an extraction
      properties:
        equals:
          description: >-
            Key-value pairs where all specified fields must equal the given
            values
          additionalProperties:
            type: string
          type: object
      type: object
    RefreshDiscoveryResponse:
      description: Result of a discovery refresh operation
      properties:
        connectionsSynced:
          description: Number of connections synced during the refresh
          example: 3
          type: integer
      type: object
    ScheduleResponse:
      description: Cron-based reconciliation schedule
      properties:
        id:
          description: Unique identifier for the schedule
          example: 019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b
          format: uuid
          type: string
        contextId:
          description: Context this schedule belongs to
          example: 019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f
          format: uuid
          type: string
        cronExpression:
          description: Cron expression defining the schedule
          example: 0 0 * * *
          maxLength: 100
          type: string
        enabled:
          description: Whether the schedule is active
          example: true
          type: boolean
        lastRunAt:
          description: Last successful run time in RFC 3339 format
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        nextRunAt:
          description: Next scheduled run time in RFC 3339 format
          example: '2025-01-16T00:00:00Z'
          format: date-time
          type: string
        createdAt:
          description: Creation timestamp in RFC 3339 format
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format
          example: '2025-01-15T10:30:00Z'
          format: date-time
          type: string
      type: object
    CreateScheduleRequest:
      description: Payload for creating a reconciliation schedule
      properties:
        cronExpression:
          description: Cron expression defining the schedule frequency
          example: 0 0 * * *
          maxLength: 100
          minLength: 1
          type: string
        enabled:
          description: Whether the schedule should be active immediately
          example: true
          type: boolean
      required:
        - cronExpression
      type: object
    UpdateScheduleRequest:
      description: Payload for updating a reconciliation schedule
      properties:
        cronExpression:
          description: Updated cron expression
          example: 0 6 * * *
          maxLength: 100
          type: string
        enabled:
          description: Updated enabled status
          example: false
          type: boolean
      type: object
    ListSchedulesResponse:
      description: Paginated list of schedules
      properties:
        items:
          items:
            $ref: '#/components/schemas/ScheduleResponse'
          maxItems: 200
          type: array
        cursor:
          description: Cursor value to retrieve the next page of results
          example: eyJpZCI6IjAxOWM5NmEwLTJiMjAtNzEyMy05YTFiLTJjM2Q0ZTVmNmE3YiJ9
          type: string
      type: object
    AdjustEntryRequest:
      description: Adjust entry request payload
      properties:
        amount:
          description: Adjustment amount
          example: 150.5
          type: number
        currency:
          description: Currency code (ISO 4217)
          example: BRL
          type: string
        effectiveAt:
          description: When the adjustment takes effect
          format: date-time
          type: string
        notes:
          description: Additional notes explaining the adjustment
          example: Correcting processing fee discrepancy
          maxLength: 1000
          type: string
        reasonCode:
          description: Reason code for the adjustment
          example: FEE_ADJUSTMENT
          maxLength: 255
          type: string
      required:
        - amount
        - currency
        - effectiveAt
        - notes
        - reasonCode
      type: object
    CloseDisputeRequest:
      description: Close dispute request payload
      properties:
        resolution:
          description: Resolution description
          example: Counterparty acknowledged the error and issued correction
          maxLength: 5000
          type: string
        won:
          description: Whether the dispute was won
          example: true
          type: boolean
      required:
        - resolution
      type: object
    DispatchRequest:
      description: Dispatch request payload
      properties:
        queue:
          description: Optional queue or team assignment
          example: RECON-TEAM
          maxLength: 255
          type: string
        targetSystem:
          description: Target system to dispatch to
          enum:
            - JIRA
            - SERVICENOW
            - WEBHOOK
            - MANUAL
          example: JIRA
          maxLength: 255
          type: string
      required:
        - targetSystem
      type: object
    DispatchResponse:
      description: Dispatch result
      properties:
        acknowledged:
          description: Whether the dispatch was acknowledged
          example: true
          type: boolean
        dispatchedAt:
          description: When the dispatch occurred in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        exceptionId:
          description: Exception ID that was dispatched
          example: 019c96a0-10d2-7134-ba5f-664142ee7052
          type: string
        externalReference:
          description: External reference ID from target system
          example: RECON-1234
          type: string
        target:
          description: Target system dispatched to
          example: JIRA
          type: string
      type: object
    DisputeResponse:
      description: Dispute details
      properties:
        category:
          description: Category of the dispute
          enum:
            - BANK_FEE_ERROR
            - UNRECOGNIZED_CHARGE
            - DUPLICATE_TRANSACTION
            - OTHER
          example: BANK_FEE_ERROR
          type: string
        createdAt:
          description: Creation timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        description:
          description: Description of the dispute
          example: Transaction amount differs from expected
          type: string
        evidence:
          description: Evidence submitted for this dispute
          items:
            $ref: '#/components/schemas/EvidenceResponse'
          type: array
        exceptionId:
          description: Exception ID this dispute is for
          example: 019c96a0-10d2-7134-ba5f-664142ee7052
          type: string
        id:
          description: Unique identifier for the dispute
          example: 019c96a0-10d2-7193-8841-0d7347efd09a
          type: string
        openedBy:
          description: User who opened the dispute
          example: user@example.com
          type: string
        reopenReason:
          description: Reason for reopening if reopened
          example: New evidence discovered
          type: string
        resolution:
          description: Resolution description when closed
          example: Counterparty confirmed error
          type: string
        state:
          description: Current state
          enum:
            - DRAFT
            - OPEN
            - PENDING_EVIDENCE
            - WON
            - LOST
          example: OPEN
          type: string
        updatedAt:
          description: Last update timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
      type: object
    EvidenceResponse:
      description: Evidence details
      properties:
        comment:
          description: Comment describing the evidence
          example: Bank statement attached
          type: string
        disputeId:
          description: Dispute ID this evidence belongs to
          example: 019c96a0-10d2-7193-8841-0d7347efd09a
          type: string
        fileUrl:
          description: URL to evidence file
          example: https://storage.example.com/evidence/doc123.pdf
          type: string
        id:
          description: Unique identifier for the evidence
          example: 019c96a0-0c0d-7915-84b9-e497bfee9916
          type: string
        submittedAt:
          description: When the evidence was submitted in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        submittedBy:
          description: User who submitted the evidence
          example: user@example.com
          type: string
      type: object
    ExceptionResponse:
      description: Exception details
      properties:
        assignedTo:
          description: User the exception is assigned to
          example: user@example.com
          type: string
        createdAt:
          description: Creation timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        dueAt:
          description: Due date for resolution in RFC3339 format
          example: 2025-01-20T10:30:00.000Z
          type: string
        externalIssueId:
          description: External issue ID in the external system
          example: RECON-1234
          type: string
        externalSystem:
          description: External system where exception was dispatched
          example: JIRA
          type: string
        id:
          description: Unique identifier for the exception
          example: 019c96a0-10d2-7134-ba5f-664142ee7052
          type: string
        reason:
          description: Reason the exception was raised
          example: Amount mismatch detected
          type: string
        resolutionNotes:
          description: Resolution notes when resolved
          example: Resolved via force match
          type: string
        resolutionReason:
          description: Reason for the resolution
          example: BUSINESS_DECISION
          type: string
        resolutionType:
          description: Type of resolution applied
          enum:
            - FORCE_MATCH
            - ADJUST_ENTRY
          example: FORCE_MATCH
          type: string
        severity:
          description: Severity level
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
          example: HIGH
          type: string
        status:
          description: Current status
          enum:
            - OPEN
            - ASSIGNED
            - PENDING_RESOLUTION
            - RESOLVED
          example: OPEN
          type: string
        transactionId:
          description: Transaction ID this exception is for
          example: 019c96a0-10ce-75fc-a273-dc799079a99c
          type: string
        updatedAt:
          description: Last update timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
      type: object
    ForceMatchRequest:
      description: Force match request payload
      properties:
        notes:
          description: Additional notes explaining the force match decision
          example: Approved by finance team after manual review
          maxLength: 1000
          type: string
        overrideReason:
          description: Reason for overriding the normal matching process
          example: BUSINESS_DECISION
          maxLength: 255
          type: string
      required:
        - notes
        - overrideReason
      type: object
    HistoryEntryResponse:
      description: Audit log entry
      properties:
        action:
          description: Action that was performed
          example: FORCE_MATCH
          type: string
        actorId:
          description: User who performed the action
          example: user@example.com
          type: string
        changes:
          description: Changes made in this action
        createdAt:
          description: When the action occurred in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        id:
          description: Unique identifier for the history entry
          example: 019c96a0-0b4e-7079-8be0-ab6bdccf975f
          type: string
      type: object
    HistoryResponse:
      description: Audit history
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          description: List of history entries
          items:
            $ref: '#/components/schemas/HistoryEntryResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
      type: object
    ListExceptionsResponse:
      description: Paginated list of exceptions
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          description: List of exceptions
          items:
            $ref: '#/components/schemas/ExceptionResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
      type: object
    OpenDisputeRequest:
      description: Open dispute request payload
      properties:
        category:
          description: Category of the dispute
          example: AMOUNT_MISMATCH
          maxLength: 255
          type: string
        description:
          description: Detailed description of the dispute
          example: Transaction amount differs from invoice
          maxLength: 5000
          type: string
      required:
        - category
        - description
      type: object
    SubmitEvidenceRequest:
      description: Submit evidence request payload
      properties:
        comment:
          description: Comment describing the evidence
          example: Attached bank statement showing correct amount
          maxLength: 1000
          type: string
        fileUrl:
          description: Optional URL to evidence file
          example: https://storage.example.com/evidence/doc123.pdf
          maxLength: 2048
          type: string
      required:
        - comment
      type: object
    AuditLogResponse:
      description: Immutable audit log entry for governance tracking
      properties:
        action:
          description: Action that was performed
          example: CREATE
          type: string
        actorId:
          description: ID of the actor who performed the action
          example: user@example.com
          type: string
        changes:
          description: Changes made to the entity
          items:
            type: integer
          type: array
        createdAt:
          description: Creation timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        entityId:
          description: ID of the entity that was modified
          example: 019c96a0-10a0-72d2-9fb0-2b7de8093182
          type: string
        entityType:
          description: Type of entity that was modified
          example: reconciliation_context
          type: string
        id:
          description: Unique identifier for the audit log entry
          example: 019c96a0-0b61-71a2-8595-dde786b5bcc6
          type: string
        tenantId:
          description: Tenant ID that owns this audit log entry
          example: 019c96a0-0a98-7287-9a31-786e0809c769
          type: string
        truncated:
          description: >-
            True when the original audit diff exceeded the payload cap and was
            replaced with a truncation marker
          example: false
          type: boolean
        originalSize:
          description: >-
            Byte size of the original diff before truncation; zero when not
            truncated
          example: 0
          format: int64
          type: integer
      type: object
    ListAuditLogsResponse:
      description: Paginated list of audit log entries
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          description: List of audit log entries
          items:
            $ref: '#/components/schemas/AuditLogResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
      type: object
    IgnoreTransactionRequest:
      description: Ignore transaction request
      properties:
        reason:
          description: Reason for ignoring the transaction
          example: Duplicate entry - already processed manually
          type: string
      required:
        - reason
      type: object
    IgnoreTransactionResponse:
      description: Ignore transaction response
      properties:
        amount:
          description: Transaction amount as string
          example: '1000.50'
          type: string
        contextId:
          description: Context ID this transaction belongs to
          example: 019c96a0-10a0-72d2-9fb0-2b7de8093182
          type: string
        createdAt:
          description: Creation timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        currency:
          description: Currency code
          example: BRL
          type: string
        date:
          description: Transaction date in RFC3339 format
          example: 2025-01-15T00:00:00.000Z
          type: string
        description:
          description: Description of the transaction
          example: Wire transfer from ABC Corp
          type: string
        externalId:
          description: External identifier from the source system
          example: TXN-12345
          type: string
        extractionStatus:
          description: Extraction status
          enum:
            - PENDING
            - EXTRACTED
            - FAILED
          example: EXTRACTED
          type: string
        id:
          description: Unique identifier for the transaction
          example: 019c96a0-10ce-75fc-a273-dc799079a99c
          type: string
        jobId:
          description: Job ID that ingested this transaction
          example: 019c96a0-10ce-75fc-a273-dc799079a99c
          type: string
        sourceId:
          description: Source ID this transaction belongs to
          example: 019c96a0-108c-7a74-8e31-3789daffe1ed
          type: string
        status:
          description: Current matching status
          enum:
            - PENDING
            - MATCHED
            - UNMATCHED
          example: PENDING
          type: string
      type: object
    JobResponse:
      description: Ingestion job details
      properties:
        completedAt:
          description: When the job completed in RFC3339 format (if completed)
          example: 2025-01-15T10:35:00.000Z
          type: string
        contextId:
          description: Context ID this job belongs to
          example: 019c96a0-10a0-72d2-9fb0-2b7de8093182
          type: string
        createdAt:
          description: Creation timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        failedRows:
          description: Number of rows that failed processing
          example: 5
          minimum: 0
          type: integer
        fileName:
          description: Original file name
          example: transactions_2024.csv
          type: string
        id:
          description: Unique identifier for the job
          example: 019c96a0-10ce-75fc-a273-dc799079a99c
          type: string
        sourceId:
          description: Source ID this job ingests data into
          example: 019c96a0-108c-7a74-8e31-3789daffe1ed
          type: string
        startedAt:
          description: When the job started in RFC3339 format (null for QUEUED jobs)
          example: 2025-01-15T10:30:00.000Z
          type: string
        status:
          description: Current status of the job
          enum:
            - QUEUED
            - PROCESSING
            - COMPLETED
            - FAILED
          example: PROCESSING
          type: string
        totalRows:
          description: Total number of rows in the file
          example: 1000
          minimum: 0
          type: integer
      type: object
    ListJobsResponse:
      description: Cursor-paginated list of ingestion jobs
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          description: List of ingestion jobs
          items:
            $ref: '#/components/schemas/JobResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
      type: object
    ListTransactionsResponse:
      description: Cursor-paginated list of transactions
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          description: List of transactions
          items:
            $ref: '#/components/schemas/TransactionResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
      type: object
    TransactionResponse:
      description: Transaction details
      properties:
        amount:
          description: Transaction amount as string
          example: '1000.50'
          type: string
        contextId:
          description: Context ID this transaction belongs to
          example: 019c96a0-10a0-72d2-9fb0-2b7de8093182
          type: string
        createdAt:
          description: Creation timestamp in RFC3339 format
          example: 2025-01-15T10:30:00.000Z
          type: string
        currency:
          description: Currency code
          example: BRL
          type: string
        date:
          description: Transaction date in RFC3339 format
          example: 2025-01-15T00:00:00.000Z
          type: string
        description:
          description: Description of the transaction
          example: Wire transfer from ABC Corp
          type: string
        externalId:
          description: External identifier from the source system
          example: TXN-12345
          type: string
        extractionStatus:
          description: Extraction status
          enum:
            - PENDING
            - EXTRACTED
            - FAILED
          example: EXTRACTED
          type: string
        id:
          description: Unique identifier for the transaction
          example: 019c96a0-10ce-75fc-a273-dc799079a99c
          type: string
        jobId:
          description: Job ID that ingested this transaction
          example: 019c96a0-10ce-75fc-a273-dc799079a99c
          type: string
        sourceId:
          description: Source ID this transaction belongs to
          example: 019c96a0-108c-7a74-8e31-3789daffe1ed
          type: string
        status:
          description: Current matching status
          enum:
            - PENDING
            - MATCHED
            - UNMATCHED
          example: PENDING
          type: string
      type: object
    AdjustmentType:
      enum:
        - BANK_FEE
        - FX_DIFFERENCE
        - ROUNDING
        - WRITE_OFF
        - MISCELLANEOUS
      type: string
      x-enum-varnames:
        - AdjustmentTypeBankFee
        - AdjustmentTypeFXDifference
        - AdjustmentTypeRounding
        - AdjustmentTypeWriteOff
        - AdjustmentTypeMiscellaneous
    MatchGroupResponse:
      properties:
        confidence:
          $ref: '#/components/schemas/ConfidenceScore'
        confirmedAt:
          type: string
        contextId:
          type: string
        createdAt:
          type: string
        id:
          type: string
        items:
          items:
            $ref: '#/components/schemas/MatchItemResponse'
          type: array
        rejectedReason:
          type: string
        ruleId:
          type: string
        runId:
          type: string
        status:
          $ref: '#/components/schemas/MatchGroupStatus'
        updatedAt:
          type: string
      type: object
    MatchItemResponse:
      properties:
        allocatedAmount:
          type: number
        allocatedCurrency:
          type: string
        allowPartial:
          type: boolean
        createdAt:
          type: string
        expectedAmount:
          type: number
        id:
          type: string
        matchGroupId:
          type: string
        transactionId:
          type: string
        updatedAt:
          type: string
      type: object
    MatchRunResponse:
      properties:
        completedAt:
          type: string
        contextId:
          type: string
        createdAt:
          type: string
        failureReason:
          type: string
        id:
          type: string
        mode:
          $ref: '#/components/schemas/MatchRunMode'
        startedAt:
          type: string
        stats:
          additionalProperties:
            type: integer
          type: object
        status:
          $ref: '#/components/schemas/MatchRunStatus'
        updatedAt:
          type: string
      type: object
    ConfidenceScore:
      type: object
    MatchGroupStatus:
      description: Lifecycle status of a match group
      enum:
        - PROPOSED
        - CONFIRMED
        - REJECTED
      type: string
      x-enum-varnames:
        - MatchGroupStatusProposed
        - MatchGroupStatusConfirmed
        - MatchGroupStatusRejected
    MatchRunMode:
      description: Execution mode for a matching run
      enum:
        - DRY_RUN
        - COMMIT
      type: string
      x-enum-varnames:
        - MatchRunModeDryRun
        - MatchRunModeCommit
    MatchRunStatus:
      description: Lifecycle status of a matching run
      enum:
        - PROCESSING
        - COMPLETED
        - FAILED
      type: string
      x-enum-varnames:
        - MatchRunStatusProcessing
        - MatchRunStatusCompleted
        - MatchRunStatusFailed
    RuleType:
      description: Type of matching rule algorithm
      enum:
        - EXACT
        - TOLERANCE
        - DATE_LAG
      type: string
      x-enum-varnames:
        - RuleTypeExact
        - RuleTypeTolerance
        - RuleTypeDateLag
    ErrorResponse:
      description: Standard error response returned by all API endpoints
      type: object
      required:
        - code
        - title
        - message
      properties:
        code:
          type: string
          description: Stable application error code.
          example: MTCH-0001
        title:
          type: string
          description: Human-readable error title.
          example: Bad Request
        message:
          type: string
          description: Human-readable error message with details.
          example: context not found
        error:
          type: string
          description: Deprecated. Error message for backward compatibility.
          deprecated: true
        details:
          description: Additional error context as key-value pairs
          additionalProperties: {}
          type: object
    CheckResult:
      description: Result of a single health dependency check
      type: object
      properties:
        status:
          description: Check result status
          enum:
            - up
            - down
            - degraded
            - skipped
            - n/a
          example: up
          type: string
        latency_ms:
          description: Round-trip latency in milliseconds
          example: 2
          type: integer
        tls:
          description: TLS posture; omitted for dependencies without a TLS concept
          type:
            - boolean
            - 'null'
        error:
          description: Error string when the check failed
          type: string
        reason:
          description: Human-readable reason for the current status
          type: string
    DependencyChecks:
      description: Individual dependency health status
      properties:
        database:
          description: 'Database check status: ok, down, or unknown'
          enum:
            - ok
            - down
            - unknown
          example: ok
          type: string
        database_replica:
          description: 'DatabaseReplica check status: ok, down, or unknown'
          enum:
            - ok
            - down
            - unknown
          example: ok
          type: string
        object_storage:
          description: 'ObjectStorage check status: ok, down, or unknown'
          enum:
            - ok
            - down
            - unknown
          example: ok
          type: string
        rabbitmq:
          description: 'RabbitMQ check status: ok, down, or unknown'
          enum:
            - ok
            - down
            - unknown
          example: ok
          type: string
        redis:
          description: 'Redis check status: ok, down, or unknown'
          enum:
            - ok
            - down
            - unknown
          example: ok
          type: string
      type: object
    HealthResponse:
      description: Service liveness status
      properties:
        status:
          description: Indicates the service health (always "healthy" if responding)
          example: healthy
          type: string
      type: object
    ReadinessResponse:
      description: Service readiness status with optional dependency checks
      properties:
        checks:
          allOf:
            - $ref: '#/components/schemas/DependencyChecks'
          description: >-
            Checks contains individual dependency status (only in non-production
            environments)
        status:
          description: >-
            Status is "ok" when all required dependencies are available,
            "degraded" otherwise
          enum:
            - ok
            - degraded
          example: ok
          type: string
      type: object
    ListContextsResponse:
      description: Cursor-paginated list of reconciliation contexts
      properties:
        items:
          description: List of reconciliation contexts
          items:
            $ref: '#/components/schemas/ReconciliationContextResponse'
          type: array
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
        hasMore:
          example: true
          type: boolean
      type: object
    ListMatchRulesResponse:
      description: Cursor-paginated list of match rules
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          description: List of match rules
          items:
            $ref: '#/components/schemas/MatchRuleResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
      type: object
    ListSourcesResponse:
      description: Cursor-paginated list of reconciliation sources
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          description: List of reconciliation sources with field map status
          items:
            $ref: '#/components/schemas/SourceWithFieldMapStatusResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
      type: object
    ReorderRequest:
      properties:
        ruleIds:
          items:
            type: string
          minItems: 1
          type: array
      required:
        - ruleIds
      type: object
    Adjustment:
      properties:
        amount:
          type: number
        contextId:
          type: string
        createdAt:
          type: string
        createdBy:
          type: string
        currency:
          type: string
        description:
          type: string
        id:
          type: string
        matchGroupId:
          type: string
        reason:
          type: string
        transactionId:
          type: string
        type:
          $ref: '#/components/schemas/AdjustmentType'
        updatedAt:
          type: string
      type: object
    AdjustmentResponse:
      properties:
        adjustment:
          $ref: '#/components/schemas/Adjustment'
      type: object
    CreateAdjustmentRequest:
      properties:
        amount:
          example: '10.50'
          type: string
        currency:
          example: BRL
          type: string
        direction:
          description: Direction of the adjustment
          enum:
            - DEBIT
            - CREDIT
          example: DEBIT
          type: string
        description:
          example: Bank wire fee adjustment
          type: string
        matchGroupId:
          example: 019c96a0-0b74-768c-8d25-2bf065dca2f8
          format: uuid
          type: string
        reason:
          example: Variance due to bank processing fee
          type: string
        transactionId:
          example: 019c96a0-10ce-75fc-a273-dc799079a99c
          format: uuid
          type: string
        type:
          enum:
            - BANK_FEE
            - FX_DIFFERENCE
            - ROUNDING
            - WRITE_OFF
            - MISCELLANEOUS
          example: BANK_FEE
          type: string
      required:
        - amount
        - currency
        - description
        - direction
        - reason
        - type
      type: object
    CreateManualMatchRequest:
      properties:
        notes:
          example: Manual match for Q4 reconciliation
          type: string
        transactionIds:
          example:
            - 019c96a0-10ce-75fc-a273-dc799079a99c
          items:
            type: string
          minItems: 2
          type: array
      required:
        - transactionIds
      type: object
    ListMatchGroupsResponse:
      description: Cursor-paginated list of match groups
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          description: List of match groups
          items:
            $ref: '#/components/schemas/MatchGroupResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
      type: object
    ListMatchRunsResponse:
      description: Cursor-paginated list of match runs
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          description: List of match runs
          items:
            $ref: '#/components/schemas/MatchRunResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          example: eyJpZCI6IjEyMiJ9
          type: string
      type: object
    ManualMatchResponse:
      properties:
        matchGroup:
          $ref: '#/components/schemas/MatchGroupResponse'
      type: object
    RunMatchRequest:
      properties:
        mode:
          enum:
            - DRY_RUN
            - COMMIT
          example: DRY_RUN
          type: string
      required:
        - mode
      type: object
    RunMatchResponse:
      properties:
        runId:
          example: 019c96a0-0b88-7725-b825-efff420e20e0
          format: uuid
          type: string
        status:
          enum:
            - PROCESSING
            - COMPLETED
            - FAILED
          example: PROCESSING
          type: string
      type: object
    UnmatchRequest:
      properties:
        reason:
          example: incorrect match - amounts do not match
          type: string
      required:
        - reason
      type: object
    AgeBucketDTO:
      properties:
        bucket:
          type: string
        value:
          type: integer
      type: object
    BreakdownMetricsResponse:
      properties:
        byAge:
          items:
            $ref: '#/components/schemas/AgeBucketDTO'
          type: array
        byReason:
          additionalProperties:
            type: integer
          type: object
        byRule:
          items:
            $ref: '#/components/schemas/RuleMatchCountDTO'
          type: array
        bySeverity:
          additionalProperties:
            type: integer
          type: object
      type: object
    CreateExportJobRequest:
      properties:
        dateFrom:
          type: string
        dateTo:
          type: string
        format:
          enum:
            - CSV
            - JSON
            - XML
          type: string
        reportType:
          enum:
            - MATCHED
            - UNMATCHED
            - SUMMARY
            - VARIANCE
          type: string
        sourceId:
          type: string
      required:
        - dateFrom
        - dateTo
        - format
        - reportType
      type: object
    CreateExportJobResponse:
      properties:
        jobId:
          type: string
        status:
          type: string
        statusUrl:
          type: string
      type: object
    DashboardAggregatesResponse:
      properties:
        matchRate:
          $ref: '#/components/schemas/MatchRateStatsResponse'
        sla:
          $ref: '#/components/schemas/SLAStatsResponse'
        updatedAt:
          type: string
        volume:
          $ref: '#/components/schemas/VolumeStatsResponse'
      type: object
    DownloadExportJobResponse:
      description: Presigned download URL and metadata for an export job file
      type: object
      properties:
        downloadUrl:
          description: Presigned URL to download the export file
          example: https://storage.example.com/exports/report.csv?token=abc
          type: string
        fileName:
          description: Original file name of the export
          example: matched_report.csv
          type: string
        sha256:
          description: SHA-256 checksum of the file for integrity verification
          example: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
          type: string
        expiresIn:
          description: Duration in seconds until the download URL expires
          example: 3600
          type: integer
    ExportCountResponse:
      description: Count of items matching an export filter
      type: object
      properties:
        count:
          description: Number of items matching the export filter
          example: 4250
          format: int64
          type: integer
    ExportJobListResponse:
      properties:
        hasMore:
          example: true
          type: boolean
        items:
          items:
            $ref: '#/components/schemas/ExportJobResponse'
          type: array
        limit:
          example: 20
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          example: eyJpZCI6IjEyMyJ9
          type: string
      type: object
    ExportJobResponse:
      properties:
        bytesWritten:
          type: integer
        createdAt:
          type: string
        downloadUrl:
          type: string
        error:
          type: string
        expiresAt:
          type: string
        fileName:
          type: string
        finishedAt:
          type: string
        format:
          type: string
        id:
          type: string
        recordsWritten:
          type: integer
        reportType:
          type: string
        startedAt:
          type: string
        status:
          type: string
      type: object
    MatchRateStatsResponse:
      properties:
        matchRate:
          type: number
        matchRateAmount:
          type: number
        matchedCount:
          type: integer
        totalCount:
          type: integer
        unmatchedCount:
          type: integer
      type: object
    MatcherDashboardMetricsResponse:
      properties:
        breakdowns:
          $ref: '#/components/schemas/BreakdownMetricsResponse'
        summary:
          $ref: '#/components/schemas/SummaryMetricsResponse'
        trends:
          $ref: '#/components/schemas/TrendMetricsResponse'
        updatedAt:
          type: string
      type: object
    RuleMatchCountDTO:
      properties:
        count:
          type: integer
        id:
          type: string
        name:
          type: string
      type: object
    SLAStatsResponse:
      properties:
        averageResolutionMs:
          type: integer
        pendingOverdue:
          type: integer
        pendingWithinSLA:
          type: integer
        resolvedLate:
          type: integer
        resolvedOnTime:
          type: integer
        slaComplianceRate:
          type: number
        totalExceptions:
          type: integer
      type: object
    SummaryMetricsResponse:
      properties:
        criticalExposure:
          type: string
        matchRate:
          type: number
        oldestExceptionAgeHours:
          type: number
        pendingExceptions:
          type: integer
        totalMatches:
          type: integer
        totalTransactions:
          type: integer
      type: object
    TrendMetricsResponse:
      properties:
        dates:
          items:
            type: string
          type: array
        exceptions:
          items:
            type: integer
          type: array
        ingestion:
          items:
            type: integer
          type: array
        matchRates:
          items:
            type: number
          type: array
        matches:
          items:
            type: integer
          type: array
      type: object
    VolumeStatsResponse:
      properties:
        matchedAmount:
          type: string
        matchedTransactions:
          type: integer
        periodEnd:
          type: string
        periodStart:
          type: string
        totalAmount:
          type: string
        totalTransactions:
          type: integer
        unmatchedAmount:
          type: string
        unmatchedCount:
          type: integer
      type: object
    CloneContextRequest:
      description: Request payload for cloning a reconciliation context
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name for the cloned context
          example: Q1 2025 Reconciliation (Copy)
          minLength: 1
          maxLength: 100
        includeSources:
          type: boolean
          description: Whether to clone associated sources
          default: true
        includeRules:
          type: boolean
          description: Whether to clone associated match rules
          default: true
    CloneContextResponse:
      description: Response after cloning a reconciliation context
      type: object
      properties:
        context:
          $ref: '#/components/schemas/ReconciliationContextResponse'
        sourcesCloned:
          type: integer
          description: Number of sources cloned
          example: 3
        rulesCloned:
          type: integer
          description: Number of match rules cloned
          example: 5
        fieldMapsCloned:
          type: integer
          description: Number of field maps cloned
          example: 3
        feeRulesCloned:
          type: integer
          description: Number of fee rules cloned
          example: 2
    ListDisputesResponse:
      description: Paginated list of disputes
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DisputeResponse'
        nextCursor:
          type: string
          description: Cursor for the next page of results
        prevCursor:
          type: string
          description: Cursor for the previous page of results
        limit:
          type: integer
          description: Maximum items per page
          example: 20
        hasMore:
          type: boolean
          description: Whether more results are available
    BulkAssignRequest:
      description: Request payload for bulk assigning exceptions
      type: object
      required:
        - exceptionIds
        - assignee
      properties:
        exceptionIds:
          type: array
          items:
            type: string
          description: List of exception IDs to assign (maximum 100)
          minItems: 1
          maxItems: 100
          example:
            - 019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f
            - 019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b
        assignee:
          type: string
          description: The team member to assign the exceptions to
          maxLength: 255
          example: john.doe@company.com
    BulkResolveRequest:
      description: Request payload for bulk resolving exceptions
      type: object
      required:
        - exceptionIds
        - resolution
      properties:
        exceptionIds:
          type: array
          items:
            type: string
          description: List of exception IDs to resolve (maximum 100)
          minItems: 1
          maxItems: 100
        resolution:
          type: string
          description: Resolution status for all exceptions
          maxLength: 255
          example: ACCEPTED
        reason:
          type: string
          description: Shared resolution reason
          maxLength: 1000
    BulkDispatchRequest:
      description: Request payload for bulk dispatching exceptions
      type: object
      required:
        - exceptionIds
        - targetSystem
      properties:
        exceptionIds:
          type: array
          items:
            type: string
          description: List of exception IDs to dispatch (maximum 100)
          minItems: 1
          maxItems: 100
        targetSystem:
          type: string
          description: Target external system
          maxLength: 255
          example: JIRA
        queue:
          type: string
          description: Target queue within the external system
          maxLength: 255
    BulkActionResponse:
      description: Response from a bulk operation with success and failure details
      type: object
      properties:
        succeeded:
          type: array
          items:
            type: string
          description: List of exception IDs that were processed successfully
        failed:
          type: array
          items:
            $ref: '#/components/schemas/BulkFailure'
          description: List of failures with exception IDs and error messages
        total:
          type: integer
          description: Total number of exceptions in the request
          example: 10
    BulkFailure:
      description: Details of a failed bulk operation item
      type: object
      properties:
        exceptionId:
          type: string
          description: The exception ID that failed
        error:
          type: string
          description: Error message describing the failure
    ProcessCallbackRequest:
      description: Callback payload from an external system
      type: object
      required:
        - externalSystem
        - externalIssueId
        - status
      properties:
        callbackType:
          type: string
          description: Type of callback event
          example: status_update
        externalSystem:
          type: string
          description: Name of the external system sending the callback
          example: JIRA
        externalIssueId:
          type: string
          description: Issue identifier in the external system
          example: RECON-1234
        status:
          type: string
          description: Current status in the external system
          example: RESOLVED
        resolutionNotes:
          type: string
          description: Notes from the external system resolution
        assignee:
          type: string
          description: Current assignee in the external system
        dueAt:
          type: string
          format: date-time
          description: Due date from the external system
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp from the external system
        payload:
          type: object
          additionalProperties: true
          description: Additional callback data from the external system
    ProcessCallbackResponse:
      description: Acknowledgement of a processed callback
      type: object
      properties:
        status:
          type: string
          description: Callback processing status
          example: accepted
    CommentResponse:
      description: A comment on an exception
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the comment
          example: 019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f
        exceptionId:
          type: string
          description: The exception this comment belongs to
        author:
          type: string
          description: Author of the comment
        content:
          type: string
          description: Comment text content
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the comment was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the comment was last updated
    ListCommentsResponse:
      description: List of comments for an exception
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CommentResponse'
    AddCommentRequest:
      description: Request payload for adding a comment to an exception
      type: object
      required:
        - content
      properties:
        content:
          type: string
          description: Comment text content
          minLength: 1
          maxLength: 5000
    UpsertActorMappingRequest:
      description: Request payload for creating or updating an actor mapping
      type: object
      properties:
        displayName:
          type: string
          description: Human-readable display name for the actor
          example: John Doe
        email:
          type: string
          format: email
          description: Email address associated with the actor
          example: john.doe@company.com
    ActorMappingResponse:
      description: >-
        An actor mapping associating a system identifier with display
        information
      type: object
      properties:
        actorId:
          type: string
          description: The actor identifier
          example: user-abc-123
        displayName:
          type: string
          description: Human-readable display name
          example: John Doe
        email:
          type: string
          description: Email address
          example: john.doe@company.com
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the mapping was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the mapping was last updated
    ArchiveMetadataResponse:
      description: Metadata for an audit log archive
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the archive
          example: 019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f
        partitionName:
          type: string
          description: Name of the archived partition
        dateRangeStart:
          type: string
          format: date-time
          description: Start of the archived date range
        dateRangeEnd:
          type: string
          format: date-time
          description: End of the archived date range
        rowCount:
          type: integer
          format: int64
          description: Number of audit log entries in the archive
        compressedSizeBytes:
          type: integer
          format: int64
          description: Size of the compressed archive in bytes
        storageClass:
          type: string
          description: Storage class of the archive
          enum:
            - STANDARD
            - GLACIER
            - DEEP_ARCHIVE
        status:
          type: string
          description: Archive status
          example: COMPLETE
        archivedAt:
          type: string
          format: date-time
          description: Timestamp when the archive was created
    ListArchivesResponse:
      description: Paginated list of audit log archives
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ArchiveMetadataResponse'
        limit:
          type: integer
          description: Maximum items per page
          example: 20
        hasMore:
          type: boolean
          description: Whether more results are available
    ArchiveDownloadResponse:
      description: Download details for an audit log archive
      type: object
      properties:
        downloadUrl:
          type: string
          description: Pre-signed URL for downloading the archive
        expiresAt:
          type: string
          format: date-time
          description: Expiration timestamp of the download URL
        checksum:
          type: string
          description: SHA-256 checksum for integrity verification
    FilePreviewResponse:
      description: Preview of a transaction file showing detected columns and sample data
      type: object
      properties:
        columns:
          type: array
          items:
            type: string
          description: Detected column names
          example:
            - date
            - amount
            - reference
            - description
        sampleRows:
          type: array
          items:
            type: array
            items:
              type: string
          description: Sample data rows
        rowCount:
          type: integer
          description: Number of sample rows returned
          example: 5
        format:
          type: string
          description: Detected file format
          example: csv
    SearchTransactionsResponse:
      description: Search results for transactions with offset pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TransactionResponse'
        total:
          type: integer
          format: int64
          description: Total number of matching transactions
        limit:
          type: integer
          description: Maximum items per page
          example: 20
        offset:
          type: integer
          description: Number of items skipped
          example: 0
    SourceBreakdownResponse:
      description: Reconciliation metrics breakdown for a single source
      type: object
      properties:
        sourceId:
          type: string
          description: Source identifier
        sourceName:
          type: string
          description: Source display name
        totalTransactions:
          type: integer
          format: int64
          description: Total number of transactions from this source
        matchedTransactions:
          type: integer
          format: int64
          description: Number of matched transactions
        unmatchedTransactions:
          type: integer
          format: int64
          description: Number of unmatched transactions
        matchRate:
          type: number
          format: double
          description: Match rate as a decimal (0.0 to 1.0)
        totalAmount:
          type: string
          description: Total transaction amount (decimal string for precision)
        unmatchedAmount:
          type: string
          description: Total unmatched amount (decimal string for precision)
        currency:
          type: string
          description: Currency code
          example: USD
    SourceBreakdownListResponse:
      description: List of source breakdown metrics
      type: object
      properties:
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceBreakdownResponse'
    CashImpactSummaryResponse:
      description: Cash impact summary showing unmatched financial exposure
      type: object
      properties:
        totalUnmatchedAmount:
          type: string
          description: Total unmatched amount across all currencies (decimal string)
        byCurrency:
          type: array
          items:
            $ref: '#/components/schemas/CurrencyExposureResponse'
          description: Breakdown by currency
        byAge:
          type: array
          items:
            $ref: '#/components/schemas/AgeExposureResponse'
          description: Breakdown by age bucket
    CurrencyExposureResponse:
      description: Unmatched exposure for a single currency
      type: object
      properties:
        currency:
          type: string
          description: Currency code
          example: USD
        amount:
          type: string
          description: Unmatched amount in this currency (decimal string)
        transactionCount:
          type: integer
          format: int64
          description: Number of unmatched transactions in this currency
    AgeExposureResponse:
      description: Unmatched exposure for a specific age bucket
      type: object
      properties:
        bucket:
          type: string
          description: Age bucket label
          example: 0-24h
        amount:
          type: string
          description: Unmatched amount in this age bucket (decimal string)
        transactionCount:
          type: integer
          format: int64
          description: Number of unmatched transactions in this age bucket
    MatchedItemResponse:
      description: A single matched transaction item
      type: object
      properties:
        transactionId:
          type: string
          description: The unique identifier of the transaction
        matchGroupId:
          type: string
          description: The identifier of the match group this transaction belongs to
        sourceId:
          type: string
          description: The identifier of the reconciliation source
        amount:
          type: string
          description: The transaction amount
        currency:
          type: string
          description: The currency code (ISO 4217)
        date:
          type: string
          format: date
          description: The transaction date
    UnmatchedItemResponse:
      description: A single unmatched transaction item
      type: object
      properties:
        transactionId:
          type: string
          description: The unique identifier of the transaction
        sourceId:
          type: string
          description: The identifier of the reconciliation source
        amount:
          type: string
          description: The transaction amount
        currency:
          type: string
          description: The currency code (ISO 4217)
        status:
          type: string
          description: The current status of the unmatched transaction
        exceptionId:
          type: string
          description: The identifier of the associated exception, if any
        dueAt:
          type: string
          format: date-time
          description: The due date for resolution, if applicable
        date:
          type: string
          format: date
          description: The transaction date
    VarianceReportRowResponse:
      description: A single row of the variance analysis report
      type: object
      properties:
        sourceId:
          type: string
          description: The identifier of the reconciliation source
        currency:
          type: string
          description: The currency code (ISO 4217)
        feeScheduleId:
          type: string
          description: Identifier of the fee schedule associated with this variance row
          example: 550e8400-e29b-41d4-a716-446655440001
        feeScheduleName:
          type: string
          description: Human-readable name of the fee schedule
          example: INTERCHANGE
        fee_type:
          type: string
          description: The type of fee
        totalExpected:
          type: string
          description: The total expected amount
        totalActual:
          type: string
          description: The total actual amount
        netVariance:
          type: string
          description: The net variance between expected and actual
        variancePct:
          type: string
          description: The variance as a percentage
    SummaryReportResponse:
      description: Aggregated reconciliation summary report
      type: object
      properties:
        matchedCount:
          type: integer
          description: Total number of matched transactions
        unmatchedCount:
          type: integer
          description: Total number of unmatched transactions
        totalAmount:
          type: string
          description: Total amount across all transactions
        matchedAmount:
          type: string
          description: Total amount of matched transactions
        unmatchedAmount:
          type: string
          description: Total amount of unmatched transactions
    CursorPagination:
      description: >
        Cursor-based pagination metadata for report endpoints. Both fields are

        opaque base64-encoded JSON cursor tokens; treat them as strings and pass

        them back unchanged in the `cursor` query parameter to navigate. An
        empty

        string means there is no further page in that direction.
      type: object
      properties:
        next:
          description: >-
            Opaque cursor for the next page. Empty when there are no more
            results.
          example: eyJpZCI6IjEyMyIsImRpcmVjdGlvbiI6Im5leHQifQ==
          type: string
        prev:
          description: Opaque cursor for the previous page. Empty when on the first page.
          example: eyJpZCI6IjEyMiIsImRpcmVjdGlvbiI6InByZXYifQ==
          type: string
    ListMatchedReportResponse:
      description: Cursor-paginated list of matched transactions
      type: object
      properties:
        items:
          description: List of matched transaction items
          type: array
          items:
            $ref: '#/components/schemas/MatchedItemResponse'
        pagination:
          $ref: '#/components/schemas/CursorPagination'
    ListUnmatchedReportResponse:
      description: Cursor-paginated list of unmatched transactions
      type: object
      properties:
        items:
          description: List of unmatched transaction items
          type: array
          items:
            $ref: '#/components/schemas/UnmatchedItemResponse'
        pagination:
          $ref: '#/components/schemas/CursorPagination'
    ListVarianceReportResponse:
      description: Cursor-paginated variance analysis report
      type: object
      properties:
        items:
          description: List of variance report rows
          type: array
          items:
            $ref: '#/components/schemas/VarianceReportRowResponse'
        pagination:
          $ref: '#/components/schemas/CursorPagination'
    BridgeReadinessSummaryResponse:
      description: >-
        Aggregate counts of Fetcher extractions partitioned by bridge readiness
        state for the requesting tenant.
      type: object
      required:
        - readyCount
        - pendingCount
        - staleCount
        - failedCount
        - inFlightCount
        - totalCount
        - staleThresholdSec
        - generatedAt
        - workerHealthy
      properties:
        readyCount:
          description: Number of extractions in the ready state.
          type: integer
          format: int64
          example: 10
        pendingCount:
          description: Number of extractions in the pending state.
          type: integer
          format: int64
          example: 5
        staleCount:
          description: Number of extractions in the stale state.
          type: integer
          format: int64
          example: 2
        failedCount:
          description: Number of extractions in the failed state.
          type: integer
          format: int64
          example: 1
        inFlightCount:
          description: >-
            Number of upstream extractions still running
            (PENDING/SUBMITTED/EXTRACTING).
          type: integer
          format: int64
          example: 3
        totalCount:
          description: Total count of extractions (sum of all buckets).
          type: integer
          format: int64
          example: 21
        staleThresholdSec:
          description: The staleness threshold in seconds used to partition extractions.
          type: integer
          format: int64
          example: 3600
        generatedAt:
          description: Timestamp when the summary was generated.
          type: string
          format: date-time
          example: '2025-01-01T00:00:00Z'
        workerLastTickAt:
          description: >-
            Latest cycle timestamp written by any bridge worker replica. Omitted
            when no heartbeat has been observed.
          type:
            - string
            - 'null'
          format: date-time
          example: '2025-01-01T00:00:00Z'
        workerStalenessSeconds:
          description: >-
            Seconds since the last worker heartbeat. Omitted alongside
            workerLastTickAt.
          type:
            - integer
            - 'null'
          format: int64
          example: 120
        workerHealthy:
          description: Server-side verdict on whether the bridge worker is healthy.
          type: boolean
          example: true
    BridgeCandidateResponse:
      description: A single drill-down row for the bridge readiness dashboard.
      type: object
      required:
        - extractionId
        - connectionId
        - status
        - readinessState
        - createdAt
        - updatedAt
        - ageSeconds
      properties:
        extractionId:
          description: The unique identifier of the extraction.
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        connectionId:
          description: The unique identifier of the connection.
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174001
        status:
          description: The extraction status.
          type: string
          example: COMPLETED
        readinessState:
          description: >-
            The bridge readiness state: pending, ready, stale, failed, or
            in_flight.
          type: string
          example: ready
        ingestionJobId:
          description: The ingestion job identifier, if linked.
          type:
            - string
            - 'null'
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174002
        fetcherJobId:
          description: The Fetcher job identifier.
          type: string
          example: fetcher-job-abc123
        createdAt:
          description: Timestamp when the extraction was created.
          type: string
          format: date-time
          example: '2025-01-01T00:00:00Z'
        updatedAt:
          description: Timestamp when the extraction was last updated.
          type: string
          format: date-time
          example: '2025-01-01T01:00:00Z'
        ageSeconds:
          description: Age of the extraction in seconds.
          type: integer
          format: int64
          example: 3600
        bridgeLastError:
          description: >-
            The last bridge error class for failed extractions (omitted for
            non-failed rows).
          type: string
          example: integrity_failed
    ListBridgeCandidatesResponse:
      description: A cursor-paginated page of bridge readiness candidates.
      type: object
      required:
        - items
        - state
        - limit
      properties:
        items:
          description: List of bridge candidates for the current page.
          type: array
          items:
            $ref: '#/components/schemas/BridgeCandidateResponse'
        nextCursor:
          description: >-
            Opaque cursor for fetching the next page. Absent when no more pages
            exist.
          type: string
          example: >-
            eyJjIjoiMjAyNS0wMS0wMVQwMDowMDowMFoiLCJpIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0=
        state:
          description: The readiness state filter applied to this page.
          type: string
          example: ready
        limit:
          description: The page size used for this response.
          type: integer
          example: 50
    ActorMappingListItemResponse:
      additionalProperties: false
      properties:
        actorId:
          description: >-
            Opaque actor identifier; PII fields are omitted from list rows by
            design
          examples:
            - user:550e8400-e29b-41d4-a716-446655440000
          type: string
        createdAt:
          description: Timestamp when the mapping was created, in RFC 3339 format (UTC)
          examples:
            - '2026-01-15T10:30:00Z'
          type: string
        updatedAt:
          description: >-
            Timestamp when the mapping was last updated, in RFC 3339 format
            (UTC)
          examples:
            - '2026-01-15T10:30:00Z'
          type: string
      required:
        - actorId
        - createdAt
        - updatedAt
      type: object
    ActorMappingListResponse:
      additionalProperties: false
      properties:
        hasMore:
          description: True when more pages are available beyond this one
          type: boolean
        items:
          description: PII-free actor mapping rows for the current page
          items:
            $ref: '#/components/schemas/ActorMappingListItemResponse'
          type:
            - array
            - 'null'
        limit:
          description: Page size applied to this response
          examples:
            - 25
          format: int64
          type: integer
        nextCursor:
          description: Cursor to fetch the next page; empty when there are no more pages
          type: string
        prevCursor:
          description: >-
            Cursor of the page that preceded this request; empty on the first
            page
          type: string
      required:
        - items
        - limit
      type: object
    AggregatorConnectionListItem:
      additionalProperties: false
      properties:
        accountRef:
          description: >-
            Stored opaque vendor account reference (Pluggy itemId, Belvo link
            id)
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          type: string
        baseUrl:
          description: Stored vendor API base URL
          examples:
            - https://api.pluggy.ai
          format: uri
          type: string
        configName:
          description: Unique connection config name (tenant-scoped)
          examples:
            - pluggy-main
          type: string
        id:
          description: Connection row id (opaque)
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          type: string
        vendor:
          description: Aggregator vendor the connection is bound to
          enum:
            - pluggy
            - belvo
          examples:
            - pluggy
          type: string
      required:
        - id
        - vendor
        - configName
        - baseUrl
        - accountRef
      type: object
    AggregatorConnectionListResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Aggregator connections on this page
          items:
            $ref: '#/components/schemas/AggregatorConnectionListItem'
          type:
            - array
            - 'null'
        limit:
          examples:
            - 20
          format: int64
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          examples:
            - eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          examples:
            - eyJpZCI6IjEyMiJ9
          type: string
      required:
        - items
        - limit
        - hasMore
      type: object
    AggregatorConnectionRequest:
      additionalProperties: false
      properties:
        accountRef:
          description: >-
            Opaque vendor account reference (Pluggy itemId, Belvo link id) the
            webhook pull threads onto its request
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          minLength: 1
          type: string
        baseUrl:
          description: Vendor API base URL, stored as the connection host
          examples:
            - https://api.pluggy.ai
          format: uri
          minLength: 1
          type: string
        clientId:
          description: Aggregator API client id (sealed; never emitted)
          minLength: 1
          type: string
        configName:
          description: >-
            Unique connection config name (tenant-scoped); the mint endpoint
            binds a token to this name
          examples:
            - pluggy-main
          minLength: 1
          type: string
        secret:
          description: Aggregator API client secret (sealed; never emitted)
          minLength: 1
          type: string
        vendor:
          description: >-
            Aggregator vendor: pluggy (Pluggy Open Finance aggregator) or belvo
            (Belvo aggregator)
          enum:
            - pluggy
            - belvo
          examples:
            - pluggy
          type: string
      required:
        - vendor
        - configName
        - baseUrl
        - accountRef
        - clientId
        - secret
      type: object
    AggregatorConnectionResponse:
      additionalProperties: false
      properties:
        accountRef:
          description: >-
            Stored opaque vendor account reference (Pluggy itemId, Belvo link
            id)
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          type: string
        baseUrl:
          description: Stored vendor API base URL
          examples:
            - https://api.pluggy.ai
          format: uri
          type: string
        configName:
          description: Connection config name the operator mints a token against
          examples:
            - pluggy-main
          type: string
        vendor:
          description: Aggregator vendor the connection is bound to
          enum:
            - pluggy
            - belvo
          examples:
            - pluggy
          type: string
      required:
        - vendor
        - configName
        - baseUrl
        - accountRef
      type: object
    ApproveExtractionResponse:
      additionalProperties: false
      properties:
        candidateCount:
          description: Number of candidates ingested through the normal pipeline
          examples:
            - 12
          format: int64
          type: integer
        ingestionJobId:
          description: Downstream ingestion job the approved candidates produced
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        reviewId:
          description: Identifier of the approved review
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
      required:
        - reviewId
        - ingestionJobId
        - candidateCount
      type: object
    ApproveRuleSuggestionResponse:
      additionalProperties: false
      properties:
        createdRuleId:
          description: Identifier of the match rule created from the approved suggestion
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        reviewId:
          description: Identifier of the approved suggestion review
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
      required:
        - reviewId
        - createdRuleId
      type: object
    AssignExceptionRequest:
      additionalProperties: false
      properties:
        assignee:
          description: User to assign the exception to
          examples:
            - user@example.com
          maxLength: 255
          minLength: 1
          type: string
      required:
        - assignee
      type: object
    AuditChainVerificationResponse:
      additionalProperties: false
      properties:
        firstBrokenSeq:
          description: >-
            tenant_seq of the first record that failed verification; omitted
            when the chain is intact
          examples:
            - 0
          format: int64
          type: integer
        intact:
          description: >-
            True when every inspected record links to the previous one and
            matches its stored hash
          examples:
            - true
          type: boolean
        truncated:
          description: >-
            True when the chain has more records than the inspection bound
            allowed; the verdict then covers only a prefix
          examples:
            - false
          type: boolean
        verifiedCount:
          description: >-
            Number of records confirmed intact (full inspected count when
            intact, otherwise the count before the first break)
          examples:
            - 1024
          format: int64
          type: integer
      required:
        - intact
        - verifiedCount
        - truncated
      type: object
    CandidateFieldResponse:
      additionalProperties: false
      properties:
        canonicalKey:
          description: Canonical field-map key (e.g. amount, external_id, currency, date)
          examples:
            - amount
          type: string
        confidence:
          description: Extractor confidence in this field, 0.0 (none) to 1.0 (certain)
          examples:
            - 0.95
          format: double
          maximum: 1
          minimum: 0
          type: number
        page:
          description: 1-based page the value was extracted from; 0 when unknown
          examples:
            - 1
          format: int64
          type: integer
        region:
          description: >-
            Best-effort region/bounding-box descriptor; empty when the source
            lane does not expose it
          type: string
        value:
          description: >-
            Verbatim string token extracted for the canonical key; money stays a
            string, never a parsed amount
          examples:
            - '100.50'
          type: string
      required:
        - canonicalKey
        - value
        - confidence
        - page
      type: object
    CandidateMatchedKey:
      additionalProperties: false
      properties:
        agreed:
          description: >-
            Whether the two transactions agree on this key under the field's
            configured mode/tolerance — the engine's own per-field gate decision
          examples:
            - true
          type: boolean
        field:
          description: Name of the configured composite match field (metadata key)
          examples:
            - payment_id
          type: string
      required:
        - field
        - agreed
      type: object
    CandidateProposalResponse:
      additionalProperties: false
      properties:
        amountDelta:
          description: candidate.amount - target.amount as a signed decimal string
          examples:
            - '0.00'
          type: string
        dateDeltaDays:
          description: Signed whole-day difference (candidate - target) in UTC days
          examples:
            - 0
          format: int64
          type: integer
        ruleId:
          description: Identifier of the rule that produced the best score for this pair
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        ruleType:
          description: Strategy of the rule that produced the best score
          examples:
            - EXACT
          type: string
        score:
          description: Engine confidence score for this pair (0..100)
          examples:
            - 90
          format: int64
          maximum: 100
          minimum: 0
          type: integer
        transaction:
          $ref: '#/components/schemas/CandidateTransactionView'
          description: The proposed counterpart transaction
        why:
          $ref: '#/components/schemas/CandidateWhy'
          description: Per-component rationale for the score
      required:
        - transaction
        - ruleId
        - ruleType
        - score
        - why
        - amountDelta
        - dateDeltaDays
      type: object
    CandidateProposalsResponse:
      additionalProperties: false
      properties:
        items:
          description: Ranked candidate proposals (highest score first)
          items:
            $ref: '#/components/schemas/CandidateProposalResponse'
          maxItems: 200
          type:
            - array
            - 'null'
        targetTransactionId:
          description: The transaction counterparts were proposed for
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
      required:
        - targetTransactionId
        - items
      type: object
    CandidateResponse:
      additionalProperties: false
      properties:
        fields:
          description: Per-field breakdown with verbatim tokens, confidence, and provenance
          items:
            $ref: '#/components/schemas/CandidateFieldResponse'
          type:
            - array
            - 'null'
        source:
          description: >-
            Extraction lane that produced this candidate: text_layer (PDF text,
            higher trust) or vision (OCR/vision model, lower trust)
          examples:
            - text_layer
          type: string
      required:
        - source
        - fields
      type: object
    CandidateTransactionView:
      additionalProperties: false
      properties:
        amount:
          description: Candidate amount as a decimal string
          examples:
            - '100.50'
          type: string
        baseAmount:
          description: >-
            Candidate base-currency amount, when the transaction was
            FX-converted
          examples:
            - '100.50'
          type: string
        currency:
          description: Candidate ISO 4217 currency code
          examples:
            - USD
          type: string
        date:
          description: Candidate transaction date (RFC 3339 timestamp)
          examples:
            - '2025-01-15T10:30:00Z'
          type: string
        externalId:
          description: External reference/id of the candidate transaction
          examples:
            - INV-1234
          type: string
        id:
          description: Candidate transaction ID (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        sourceId:
          description: Source the candidate belongs to (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
          type: string
      required:
        - id
        - sourceId
        - amount
        - currency
        - date
      type: object
    CandidateWhy:
      additionalProperties: false
      properties:
        amountMatch:
          description: >-
            Whether the amounts are literally equal on the matched rule's sign
            axis (not merely within tolerance)
          examples:
            - true
          type: boolean
        currencyMatch:
          description: Whether the currency codes are literally equal and both non-empty
          examples:
            - true
          type: boolean
        dateMatch:
          description: >-
            Whether both transactions fall on the same UTC calendar day (not the
            full DATE_LAG window)
          examples:
            - true
          type: boolean
        matchedKeys:
          description: >-
            Per-key agreement for the matched rule's configured composite match
            fields (matchFields), in field-name order. Empty when the matched
            rule declares no active matchFields.
          items:
            $ref: '#/components/schemas/CandidateMatchedKey'
          type:
            - array
            - 'null'
        referenceScore:
          description: Graded 0..1 reference-similarity contribution
          examples:
            - 1
          format: double
          maximum: 1
          minimum: 0
          type: number
      required:
        - amountMatch
        - currencyMatch
        - dateMatch
        - referenceScore
      type: object
    ConnectionProvisioningRequest:
      additionalProperties: false
      properties:
        configName:
          description: Connection configuration name
          examples:
            - prod-ledger-db
          minLength: 1
          type: string
        databaseName:
          description: Database name
          examples:
            - ledger
          minLength: 1
          type: string
        databaseType:
          description: >-
            Database engine type; canonical token or a common alias (e.g.
            postgres -> POSTGRESQL, mysql -> MYSQL)
          examples:
            - POSTGRESQL
          minLength: 1
          type: string
        host:
          description: Database host
          examples:
            - db.internal.example.com
          minLength: 1
          type: string
        password:
          type: string
        port:
          description: Database TCP port (1-65535)
          examples:
            - 5432
          format: int64
          maximum: 65535
          minimum: 1
          type: integer
        schema:
          description: Optional schema/namespace within the database
          examples:
            - public
          type: string
        userName:
          description: Database user name the connection authenticates as
          examples:
            - matcher_ro
          minLength: 1
          type: string
      required:
        - configName
        - databaseType
        - host
        - port
        - databaseName
        - userName
      type: object
    ConnectionUpdateRequest:
      additionalProperties: false
      properties:
        configName:
          description: Connection configuration name
          examples:
            - prod-ledger-db
          minLength: 1
          type: string
        databaseName:
          description: Database name
          examples:
            - ledger
          minLength: 1
          type: string
        databaseType:
          description: >-
            Database engine type; canonical token or a common alias (e.g.
            postgres -> POSTGRESQL, mysql -> MYSQL)
          examples:
            - POSTGRESQL
          minLength: 1
          type: string
        host:
          description: Database host
          examples:
            - db.internal.example.com
          minLength: 1
          type: string
        password:
          type: string
        port:
          description: Database TCP port (1-65535)
          examples:
            - 5432
          format: int64
          maximum: 65535
          minimum: 1
          type: integer
        schema:
          description: Optional schema/namespace within the database
          examples:
            - public
          type: string
        userName:
          description: Database user name the connection authenticates as
          examples:
            - matcher_ro
          minLength: 1
          type: string
      type: object
    ConnectorTypeListResponse:
      additionalProperties: false
      properties:
        types:
          description: >-
            Connector types registered in the live engine for this deployment,
            deterministically ordered
          items:
            $ref: '#/components/schemas/ConnectorTypeResponse'
          type:
            - array
            - 'null'
      required:
        - types
      type: object
    ConnectorTypeResponse:
      additionalProperties: false
      properties:
        category:
          description: 'Backend-derived taxonomy bucket: ''database'' or ''rest'''
          enum:
            - database
            - rest
          examples:
            - database
          type: string
        type:
          description: Canonical engine datasource-type token
          examples:
            - POSTGRESQL
          type: string
      required:
        - type
        - category
      type: object
    CreateLayoutTemplateRequest:
      additionalProperties: false
      properties:
        discriminatorLength:
          description: Discriminator width in bytes
          examples:
            - 1
          format: int64
          minimum: 1
          type: integer
        discriminatorStart:
          description: Zero-based byte offset of the record-type discriminator
          examples:
            - 0
          format: int64
          minimum: 0
          type: integer
        family:
          description: Format family the template namespaces under
          examples:
            - cnab400
          minLength: 1
          type: string
        records:
          description: Record types declared by the layout
          items:
            $ref: '#/components/schemas/LayoutTemplateRecordRequest'
          minItems: 1
          type:
            - array
            - 'null'
        region:
          description: ISO alpha-2 region (uppercased) or XX
          examples:
            - BR
          minLength: 1
          type: string
        requiredFields:
          description: Field names the variant must declare
          items:
            type: string
          type:
            - array
            - 'null'
        variant:
          description: Operator/brand variant axis
          examples:
            - acme-cobranca
          minLength: 1
          type: string
      required:
        - region
        - family
        - variant
        - discriminatorStart
        - discriminatorLength
        - records
      type: object
    CreateSourceBindingRequest:
      additionalProperties: false
      properties:
        connectionId:
          description: >-
            Query-rail engine connection reference (UUID). Required for the
            query rail, rejected for the file rail.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        enabled:
          description: Whether the binding runs immediately. Defaults to true when omitted.
          examples:
            - true
          type: boolean
        format:
          description: >-
            Declared format the binding produces, as a region/family-namespaced
            descriptor key.
          examples:
            - br/cnab400/default
          maxLength: 255
          minLength: 1
          type: string
        kind:
          description: >-
            Rail the source is pulled on. file fetches files via a transport;
            query pulls rows through a discovery-engine connection. Exactly one
            rail payload is meaningful per kind.
          enum:
            - file
            - query
          examples:
            - file
          type: string
        scheduleSpec:
          description: >-
            Interval schedule spec the binding scheduler reads (cron or @every
            duration).
          examples:
            - '@every 1h'
          maxLength: 100
          minLength: 1
          type: string
        transportConfig:
          $ref: '#/components/schemas/SourceBindingTransportConfigRequest'
          description: >-
            File-rail transport configuration. Required for the file rail,
            rejected for the query rail.
      required:
        - kind
        - format
        - scheduleSpec
      type: object
    CredentialMetadata:
      additionalProperties: false
      properties:
        createdAt:
          description: Mint time (RFC 3339, UTC)
          type: string
        externalSystem:
          description: Operator-legible external-system label
          type: string
        id:
          description: Surrogate id of the credential
          format: uuid
          type: string
        lastUsedAt:
          description: >-
            When this credential last authenticated an inbound callback (RFC
            3339, UTC); absent until first use
          type: string
        revokedAt:
          description: When this credential was revoked (RFC 3339, UTC); absent if live
          type: string
        rotatedAt:
          description: >-
            When this credential superseded a prior one via rotation (RFC 3339,
            UTC); absent if minted fresh
          type: string
      required:
        - id
        - createdAt
      type: object
    CredentialSecretResponse:
      additionalProperties: false
      properties:
        createdAt:
          description: Mint time (RFC 3339, UTC)
          type: string
        credentialId:
          description: Surrogate id of the minted credential
          format: uuid
          type: string
        externalSystem:
          description: Operator-legible external-system label, echoed for confirmation
          type: string
        token:
          description: >-
            Raw bearer token, surfaced exactly once; configure it as the
            X-Callback-Token header value in the external system. Only its
            SHA-256 hash is stored server-side.
          type: string
        webhookUrlHint:
          description: >-
            Informational inbound-callback URL shape to configure in the
            external system. The {exceptionId} placeholder is filled per
            callback.
          type: string
      required:
        - token
        - credentialId
        - createdAt
      type: object
    Detail:
      additionalProperties: false
      properties:
        code:
          description: >-
            Stable, machine-readable domain error code scoped to the emitting
            service (format: <SERVICE>-NNNN).
          examples:
            - ERR-0001
          type: string
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    DialectResponse:
      additionalProperties: false
      properties:
        dateStyle:
          description: >-
            Detected date convention: iso (YYYY-MM-DD), iso_offset (RFC 3339
            with offset), dmy (DD/MM/YYYY), or mdy (MM/DD/YYYY)
          examples:
            - iso
          type: string
        decimalStyle:
          description: 'Detected amount decimal convention: dot (1234.56) or comma (1234,56)'
          examples:
            - comma
          type: string
        delimiter:
          description: 'Detected CSV field separator: comma, semicolon, tab, or pipe'
          examples:
            - semicolon
          type: string
        encoding:
          description: >-
            Detected file character encoding: utf-8, utf-8-sig (UTF-8 with BOM),
            cp1252 (Windows Latin-1), or iso-8859-1
          examples:
            - utf-8
          type: string
      required:
        - encoding
        - delimiter
        - decimalStyle
        - dateStyle
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    ExtractDocumentResponse:
      additionalProperties: false
      properties:
        candidateCount:
          description: Number of transaction candidates queued for review
          examples:
            - 12
          format: int64
          type: integer
        reviewId:
          description: Identifier of the queued extraction review
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        status:
          description: >-
            Lifecycle status of the queued review (always PENDING_REVIEW on
            enqueue)
          examples:
            - PENDING_REVIEW
          type: string
      required:
        - reviewId
        - candidateCount
        - status
      type: object
    ExtractionReviewListResponse:
      additionalProperties: false
      properties:
        items:
          description: Extraction reviews on this page
          items:
            $ref: '#/components/schemas/ExtractionReviewResponse'
          type:
            - array
            - 'null'
        limit:
          description: Page size requested
          examples:
            - 50
          format: int64
          type: integer
        nextCursor:
          description: Opaque cursor for the next page; empty when there are no more pages
          type: string
        prevCursor:
          description: Opaque cursor for the previous page; empty when at the start
          type: string
      required:
        - items
        - limit
      type: object
    ExtractionReviewResponse:
      additionalProperties: false
      properties:
        candidates:
          description: Proposed transaction candidates awaiting review
          items:
            $ref: '#/components/schemas/CandidateResponse'
          type:
            - array
            - 'null'
        contextId:
          description: Reconciliation context the candidates belong to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        createdAt:
          description: Creation timestamp (RFC 3339, UTC)
          examples:
            - '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        id:
          description: Review identifier
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        ingestionJobId:
          description: Downstream ingestion job linked on approval; null until linked
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        rejectReason:
          description: Free-text reason captured on rejection; empty otherwise
          type: string
        reviewerId:
          description: >-
            Principal id of the human who adjudicated the review; empty until
            decided
          type: string
        sourceId:
          description: Reconciliation source the candidates belong to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        status:
          description: >-
            Review lifecycle: PENDING_REVIEW (awaiting decision), APPROVED
            (candidates ingested), REJECTED (discarded)
          examples:
            - PENDING_REVIEW
          type: string
        updatedAt:
          description: Last-update timestamp (RFC 3339, UTC)
          examples:
            - '2025-01-15T10:35:00Z'
          format: date-time
          type: string
        version:
          description: Optimistic-concurrency version, incremented on each state change
          examples:
            - 1
          format: int64
          type: integer
      required:
        - id
        - contextId
        - sourceId
        - status
        - candidates
        - version
        - createdAt
        - updatedAt
      type: object
    FetchTriggerRequest:
      additionalProperties: false
      properties:
        connectOptions:
          additionalProperties:
            type: string
          description: >-
            Optional non-secret transport tuning (e.g. known_hosts, user,
            timeout_seconds)
          type: object
        credentialRef:
          description: Opaque stored-credential reference (not a secret)
          examples:
            - cred-handle-123
          minLength: 1
          type: string
        format:
          description: >-
            Fallback content-format hint applied when a fetched object declares
            none. Accepts the namespaced FormatDescriptor key
            (region/family/variant) or the legacy flat aliases (cnab240,
            cielo_edi, ...); both resolve through the same parser registry
          examples:
            - br/cnab240/febraban-base
          type: string
        glob:
          description: Optional glob filter; empty fetches all
          examples:
            - '*.ret'
          type: string
        host:
          description: Remote endpoint hostname or IP
          examples:
            - sftp.bank.example
          minLength: 1
          type: string
        kind:
          description: Transport kind selecting the adapter
          enum:
            - sftp
            - https
            - s3
            - imap
          examples:
            - sftp
          type: string
        path:
          description: Remote directory to list/fetch from
          examples:
            - outbound/returns
          minLength: 1
          type: string
        port:
          description: Remote endpoint port
          examples:
            - 22
          format: int64
          maximum: 65535
          minimum: 1
          type: integer
      required:
        - host
        - port
        - path
        - credentialRef
      type: object
    FetchTriggerResponse:
      additionalProperties: false
      properties:
        files:
          description: Per-file outcomes of the fetch-and-ingest batch, in fetch order
          items:
            $ref: '#/components/schemas/FileOutcomeResponse'
          type:
            - array
            - 'null'
      required:
        - files
      type: object
    FieldProposalResponse:
      additionalProperties: false
      properties:
        canonicalKey:
          description: Canonical field-map key the proposal targets
          examples:
            - amount
          type: string
        confidence:
          description: Advisor confidence in this mapping, 0.0 (none) to 1.0 (certain)
          examples:
            - 0.92
          format: double
          maximum: 1
          minimum: 0
          type: number
        rationale:
          description: Short human-readable explanation for the suggestion
          examples:
            - numeric column with comma decimal
          type: string
        sourceColumn:
          description: Proposed source column feeding the canonical key
          examples:
            - value
          type: string
      required:
        - canonicalKey
        - sourceColumn
        - confidence
        - rationale
      type: object
    FileOutcomeResponse:
      additionalProperties: false
      properties:
        error:
          description: Per-file intake failure message; empty on success
          examples:
            - ''
          type: string
        ingestionJobId:
          description: Downstream ingestion job id; empty when the object failed intake
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        name:
          description: Fetched object's base name
          examples:
            - statement-2025-06.ret
          type: string
        transactionCount:
          description: Number of transactions ingested from this object; zero on failure
          examples:
            - 42
          format: int64
          type: integer
      required:
        - name
        - transactionCount
      type: object
    FormatCatalogFamily:
      additionalProperties: false
      properties:
        family:
          description: Closed-enum format family name (e.g. cnab240, delimited, camt)
          examples:
            - cnab240
          type: string
        variants:
          description: >-
            Brand/bank variants under this family, sorted by variant; a
            single-canonical-layout family (e.g. camt) yields one entry with an
            empty variant
          items:
            $ref: '#/components/schemas/FormatCatalogVariant'
          type:
            - array
            - 'null'
      required:
        - family
        - variants
      type: object
    FormatCatalogRegion:
      additionalProperties: false
      properties:
        families:
          description: Format families under this region, sorted by family
          items:
            $ref: '#/components/schemas/FormatCatalogFamily'
          type:
            - array
            - 'null'
        region:
          description: >-
            Region code: ISO-3166 alpha-2 uppercased, or XX for region-neutral
            formats
          examples:
            - BR
          type: string
      required:
        - region
        - families
      type: object
    FormatCatalogResponse:
      additionalProperties: false
      properties:
        regions:
          description: >-
            Region axis of the catalog (ISO-3166 alpha-2 uppercased, or XX for
            region-neutral formats), sorted by region code
          items:
            $ref: '#/components/schemas/FormatCatalogRegion'
          type:
            - array
            - 'null'
      required:
        - regions
      type: object
    FormatCatalogVariant:
      additionalProperties: false
      properties:
        key:
          description: >-
            Canonical namespaced registry key (region/family[/variant]); the
            identity an upload or source declaration pins
          examples:
            - br/cnab240/febraban-base
          type: string
        variant:
          description: >-
            Open brand/bank axis (e.g. itau, febraban-base); empty for a
            single-canonical-layout family
          examples:
            - febraban-base
          type: string
      required:
        - variant
        - key
      type: object
    JobRowErrorResponse:
      additionalProperties: false
      properties:
        field:
          description: Source field the error relates to; empty when the whole row failed
          examples:
            - amount
          type: string
        message:
          description: Human-readable error reason
          examples:
            - invalid decimal
          type: string
        row:
          description: 1-based row number in the uploaded file
          examples:
            - 15
          format: int64
          minimum: 0
          type: integer
      required:
        - row
        - message
      type: object
    LayoutTemplateDiscriminatorResponse:
      additionalProperties: false
      properties:
        length:
          description: Discriminator width in bytes
          examples:
            - 1
          format: int64
          type: integer
        startByte:
          description: Zero-based byte offset of the record-type discriminator
          examples:
            - 0
          format: int64
          type: integer
      required:
        - startByte
        - length
      type: object
    LayoutTemplateFieldRequest:
      additionalProperties: false
      properties:
        kind:
          description: >-
            Value type: string (raw text), decimal (money/numeric verbatim
            token, parsed downstream), or date. A money column MUST be decimal
          examples:
            - decimal
          type: string
        length:
          description: Field width in bytes (must be greater than 0)
          examples:
            - 12
          format: int64
          type: integer
        name:
          description: >-
            Canonical field name this byte slice feeds (e.g. external_id,
            amount, currency, date)
          examples:
            - amount
          type: string
        startByte:
          description: Zero-based byte offset where the field begins
          examples:
            - 11
          format: int64
          type: integer
      required:
        - name
        - startByte
        - length
        - kind
      type: object
    LayoutTemplateFieldResponse:
      additionalProperties: false
      properties:
        kind:
          description: >-
            Value type: string (raw text), decimal (money/numeric verbatim
            token, parsed downstream), or date
          examples:
            - decimal
          type: string
        length:
          description: Field width in bytes
          examples:
            - 12
          format: int64
          type: integer
        name:
          description: >-
            Canonical field name this byte slice feeds (e.g. external_id,
            amount, currency, date)
          examples:
            - amount
          type: string
        startByte:
          description: Zero-based byte offset where the field begins
          examples:
            - 11
          format: int64
          type: integer
      required:
        - name
        - startByte
        - length
        - kind
      type: object
    LayoutTemplateRecordRequest:
      additionalProperties: false
      properties:
        fields:
          description: Ordered positional fields of this record type
          items:
            $ref: '#/components/schemas/LayoutTemplateFieldRequest'
          type:
            - array
            - 'null'
        recordType:
          description: Record-type value the discriminator byte slice must match (e.g. "1")
          examples:
            - '1'
          type: string
        width:
          description: Fixed width in bytes every record of this type must be
          examples:
            - 33
          format: int64
          type: integer
      required:
        - recordType
        - width
        - fields
      type: object
    LayoutTemplateRecordResponse:
      additionalProperties: false
      properties:
        fields:
          description: Ordered positional fields of this record type
          items:
            $ref: '#/components/schemas/LayoutTemplateFieldResponse'
          type:
            - array
            - 'null'
        recordType:
          description: Record-type value the discriminator byte slice matches (e.g. "1")
          examples:
            - '1'
          type: string
        width:
          description: Fixed width in bytes every record of this type must be
          examples:
            - 33
          format: int64
          type: integer
      required:
        - recordType
        - width
        - fields
      type: object
    LayoutTemplateResponse:
      additionalProperties: false
      properties:
        createdAt:
          description: Creation timestamp (RFC 3339, UTC)
          examples:
            - '2025-01-15T10:30:00Z'
          format: date-time
          type: string
        discriminator:
          $ref: '#/components/schemas/LayoutTemplateDiscriminatorResponse'
          description: >-
            Record-type discriminator byte range the parser reads to select a
            record type
        formatKey:
          description: >-
            Canonical format descriptor key (region/family/variant) the template
            registers under
          examples:
            - br/cnab400/acme-cobranca
          type: string
        id:
          description: Template identifier
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        recordTypeCount:
          description: Number of record types the layout declares
          examples:
            - 1
          format: int64
          type: integer
        recordWidths:
          additionalProperties:
            format: int64
            type: integer
          description: Per-record-type fixed width in bytes, keyed by record type
          type: object
        records:
          description: >-
            Record types the layout declares, each with its fixed width and
            ordered byte-range fields, sorted by record type
          items:
            $ref: '#/components/schemas/LayoutTemplateRecordResponse'
          type:
            - array
            - 'null'
        requiredFields:
          description: Field names the variant must declare across its record types
          items:
            type: string
          type:
            - array
            - 'null'
        variantKey:
          description: In-file variant key the layout is keyed by
          examples:
            - acme-cobranca
          type: string
      required:
        - id
        - formatKey
        - variantKey
        - recordTypeCount
        - discriminator
        - records
        - recordWidths
        - requiredFields
        - createdAt
      type: object
    ListContextFieldMapsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          items:
            $ref: '#/components/schemas/FieldMapResponse'
          maxItems: 200
          type:
            - array
            - 'null'
        limit:
          examples:
            - 20
          format: int64
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          examples:
            - eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          examples:
            - eyJpZCI6IjEyMiJ9
          type: string
      required:
        - items
        - limit
        - hasMore
      type: object
    ListJobErrorsResponse:
      additionalProperties: false
      properties:
        errorCap:
          description: Maximum number of row errors stored per job
          examples:
            - 100
          format: int64
          minimum: 0
          type: integer
        items:
          description: Stored row errors ordered by row number (capped at errorCap per job)
          items:
            $ref: '#/components/schemas/JobRowErrorResponse'
          maxItems: 100
          type:
            - array
            - 'null'
        storedErrors:
          description: Number of row errors actually stored for this job
          examples:
            - 100
          format: int64
          minimum: 0
          type: integer
        totalErrors:
          description: Total number of failed rows for the job (may exceed storedErrors)
          examples:
            - 1000
          format: int64
          minimum: 0
          type: integer
        truncated:
          description: True when more rows failed than were stored
          examples:
            - true
          type: boolean
      required:
        - items
        - totalErrors
        - storedErrors
        - errorCap
        - truncated
      type: object
    ListLayoutTemplatesResponse:
      additionalProperties: false
      properties:
        items:
          description: Active operator layout templates
          items:
            $ref: '#/components/schemas/LayoutTemplateResponse'
          type:
            - array
            - 'null'
      required:
        - items
      type: object
    ListOpenItemsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Page of open items
          items:
            $ref: '#/components/schemas/OpenItemResponse'
          maxItems: 200
          type:
            - array
            - 'null'
        limit:
          examples:
            - 20
          format: int64
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          examples:
            - eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          examples:
            - eyJpZCI6IjEyMiJ9
          type: string
      required:
        - items
        - limit
        - hasMore
      type: object
    ListResponse:
      additionalProperties: false
      properties:
        credentials:
          description: >-
            The tenant's callback credentials (live and revoked), newest first.
            Metadata only — never the token or hash.
          items:
            $ref: '#/components/schemas/CredentialMetadata'
          type:
            - array
            - 'null'
      required:
        - credentials
      type: object
    ListSourceBindingsResponse:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/SourceBindingResponse'
          maxItems: 200
          type:
            - array
            - 'null'
      required:
        - items
      type: object
    MappingProposalResponse:
      additionalProperties: false
      properties:
        dialect:
          $ref: '#/components/schemas/DialectResponse'
          description: >-
            Proposed source dialect; null when the advisor has no dialect
            suggestion
        fields:
          description: Per-field breakdown backing the proposed mapping
          items:
            $ref: '#/components/schemas/FieldProposalResponse'
          type:
            - array
            - 'null'
        mapping:
          additionalProperties: {}
          description: >-
            Proposed canonical field map (canonical key -> source column); null
            when the advisor could not propose a mapping
          type: object
      required:
        - fields
      type: object
    MintCredentialRequest:
      additionalProperties: false
      properties:
        externalSystem:
          description: >-
            Optional operator-legible label for the external system this
            credential authenticates (e.g. "stripe", "billing-gw")
          examples:
            - stripe
          maxLength: 128
          type: string
      type: object
    MintRequest:
      additionalProperties: false
      properties:
        connection_config_name:
          description: Config name of the existing aggregator connection the token binds to
          examples:
            - pluggy-main
          minLength: 1
          type: string
        vendor:
          description: >-
            Aggregator vendor the token is minted for: pluggy (Pluggy) or belvo
            (Belvo)
          enum:
            - pluggy
            - belvo
          examples:
            - pluggy
          type: string
      required:
        - vendor
        - connection_config_name
      type: object
    MintResponse:
      additionalProperties: false
      properties:
        token:
          description: >-
            Raw bearer token, surfaced exactly once; only its SHA-256 hash is
            stored server-side
          type: string
        vendor:
          description: Aggregator vendor the token is bound to
          enum:
            - pluggy
            - belvo
          examples:
            - pluggy
          type: string
        webhook_url:
          description: >-
            Fully-formed provider-facing receiver URL embedding the raw token in
            its path segment; configure this in the vendor dashboard
          type: string
      required:
        - token
        - webhook_url
        - vendor
      type: object
    OpenItemResponse:
      additionalProperties: false
      properties:
        ageDays:
          description: >-
            Whole days the obligation has been open, measured from its aging
            anchor (the obligation business date, or first-seen time as a
            fallback)
          examples:
            - 12
          format: int64
          minimum: 0
          type: integer
        contextId:
          description: Reconciliation context ID this open item belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        createdAt:
          description: Creation timestamp (RFC 3339)
          examples:
            - '2025-01-15T10:30:00Z'
          type: string
        currency:
          description: ISO 4217 currency code of the open item
          examples:
            - USD
          type: string
        expectedBalance:
          description: >-
            Original outstanding obligation when the item was first opened, as a
            decimal string
          examples:
            - '1000.00'
          type: string
        firstSeenAt:
          description: When this open item was first materialized in the ledger (RFC 3339)
          examples:
            - '2025-01-15T10:30:00Z'
          type: string
        id:
          description: Unique identifier for the open item
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        identityKey:
          description: >-
            Deterministic cross-run identity projection (composite match keys +
            currency) the carry-forward netting resolves on
          examples:
            - invoice=INV-1001|currency=USD
          type: string
        lastActivityAt:
          description: Timestamp of the most recent leg or transition (RFC 3339)
          examples:
            - '2025-01-20T09:00:00Z'
          type: string
        obligationDate:
          description: >-
            Business date of the originating obligation (the aging anchor, RFC
            3339); absent when none was captured
          examples:
            - '2025-01-10T00:00:00Z'
          type: string
        runId:
          description: >-
            Match run that applied the most recent settling leg. Absent for a
            freshly-opened residual that has not yet netted any leg
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        runningBalance:
          description: >-
            Outstanding amount still to be netted, as a decimal string; nets
            down toward zero as settling legs arrive
          examples:
            - '250.00'
          type: string
        status:
          description: >-
            Lifecycle status: OPEN (fresh residual), PARTIALLY_CLEARED (a leg
            netted but a residual remains), CLEARED (netted within tolerance),
            or AGED (exceeded its aging threshold while still open)
          examples:
            - PARTIALLY_CLEARED
          type: string
        transactionId:
          description: >-
            Transaction the open item most recently netted on (the latest
            settling leg). Absent for a freshly-opened residual that has not yet
            netted any leg — drill into the transaction this resolves on
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        updatedAt:
          description: Last update timestamp (RFC 3339)
          examples:
            - '2025-01-20T09:00:00Z'
          type: string
      required:
        - id
        - contextId
        - identityKey
        - currency
        - expectedBalance
        - runningBalance
        - status
        - ageDays
        - firstSeenAt
        - lastActivityAt
        - createdAt
        - updatedAt
      type: object
    ProposeMappingRequest:
      additionalProperties: false
      properties:
        format:
          description: Declared file format hint
          enum:
            - csv
            - json
            - xml
            - camt053
          examples:
            - csv
          type: string
        hints:
          additionalProperties:
            type: string
          description: >-
            Optional non-secret operator nudges (e.g. locale=pt-BR,
            has_header=true)
          type: object
        sample:
          description: Representative source-file sample
          examples:
            - |
              id;value;ccy;posted_at
              A1;10,50;BRL;2025-06-01
          minLength: 1
          type: string
      required:
        - sample
      type: object
    RejectExtractionRequest:
      additionalProperties: false
      properties:
        reason:
          description: Optional free-text reason for the rejection
          examples:
            - poor scan quality, re-upload
          type: string
      type: object
    RejectRuleSuggestionRequest:
      additionalProperties: false
      properties:
        reason:
          description: Optional rejection reason
          examples:
            - too aggressive
          maxLength: 1000
          type: string
      type: object
    ResolveExceptionRequest:
      additionalProperties: false
      properties:
        reason:
          description: Optional reason for the resolution
          examples:
            - Variance within tolerance
          maxLength: 1000
          type: string
        resolution:
          description: Resolution type applied
          examples:
            - ACCEPTED
          maxLength: 255
          minLength: 1
          type: string
      required:
        - resolution
      type: object
    RuleSuggestionCandidateResponse:
      additionalProperties: false
      properties:
        confidence:
          description: >-
            Advisor confidence in the suggestion, from 0.0 (lowest) to 1.0
            (highest)
          examples:
            - 0.82
          format: double
          type: number
        config:
          additionalProperties: {}
          description: >-
            Per-type rule configuration over the closed schema; the shape
            depends on the candidate type
          type: object
        expectedImprovement:
          description: >-
            Advisory note on the expected auto-match-rate effect; never a
            monetary figure
          examples:
            - +8% auto-match
          type: string
        priority:
          description: Proposed rule priority in the range 1..1000 (lower runs first)
          examples:
            - 10
          format: int64
          type: integer
        rationale:
          description: Short human-readable rationale for the suggestion
          examples:
            - near-miss amounts cluster under 1%
          type: string
        type:
          description: >-
            Proposed rule type from the closed vocabulary: EXACT (strict
            equality), TOLERANCE (within an amount band), or DATE_LAG (allowing
            a settlement-date offset)
          examples:
            - TOLERANCE
          type: string
      required:
        - type
        - priority
        - config
        - rationale
        - confidence
      type: object
    RuleSuggestionListResponse:
      additionalProperties: false
      properties:
        items:
          description: Page of rule-suggestion reviews
          items:
            $ref: '#/components/schemas/RuleSuggestionResponse'
          type:
            - array
            - 'null'
        limit:
          description: Maximum number of items requested for this page
          examples:
            - 20
          format: int64
          type: integer
        nextCursor:
          description: >-
            Opaque cursor for the next page; empty when there are no more
            results
          examples:
            - eyJpZCI6IjEyMyJ9
          type: string
        prevCursor:
          description: Opaque cursor for the previous page; empty on the first page
          examples:
            - eyJpZCI6IjEyMiJ9
          type: string
      required:
        - items
        - limit
      type: object
    RuleSuggestionResponse:
      additionalProperties: false
      properties:
        candidate:
          $ref: '#/components/schemas/RuleSuggestionCandidateResponse'
          description: The config-only proposed match rule
        contextId:
          description: Reconciliation context ID this suggestion belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        createdAt:
          description: When the review was created (RFC 3339)
          examples:
            - '2026-06-16T10:30:00Z'
          type: string
        createdRuleId:
          description: >-
            Identifier of the match rule created on approval; empty until an
            approved review is linked
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        id:
          description: Unique identifier for the review
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        rejectReason:
          description: Optional reason recorded when the suggestion is rejected
          examples:
            - too aggressive
          type: string
        reviewerId:
          description: >-
            Principal id of the reviewer; empty until the suggestion is
            adjudicated
          examples:
            - user-42
          type: string
        status:
          description: >-
            Lifecycle status: PENDING_REVIEW (awaiting human decision), APPROVED
            (rule created), or REJECTED (discarded)
          examples:
            - PENDING_REVIEW
          type: string
        updatedAt:
          description: When the review was last updated (RFC 3339)
          examples:
            - '2026-06-16T10:35:00Z'
          type: string
        version:
          description: Optimistic-concurrency version of the review
          examples:
            - 1
          format: int64
          type: integer
      required:
        - id
        - contextId
        - candidate
        - status
        - version
        - createdAt
        - updatedAt
      type: object
    SelectExceptionIDsResponse:
      additionalProperties: false
      properties:
        ids:
          description: >-
            Exception ids matching the filter, deterministically ordered
            (created_at DESC, id DESC), capped at 10000
          items:
            type: string
          maxItems: 10000
          type:
            - array
            - 'null'
        total:
          description: >-
            Total exceptions matching the filter (full set; may exceed the
            returned ids)
          examples:
            - 530
          format: int64
          type: integer
        truncated:
          description: >-
            True when the filtered set exceeds the returned ids (the cap was
            reached); a single bulk pass will not cover every match
          examples:
            - false
          type: boolean
      required:
        - ids
        - total
        - truncated
      type: object
    SetupProgressFieldMapsResponse:
      additionalProperties: false
      properties:
        mappedSources:
          description: Number of sources that have a field map configured.
          examples:
            - 2
          format: int64
          type: integer
      required:
        - mappedSources
      type: object
    SetupProgressLastRunResponse:
      additionalProperties: false
      properties:
        completedAt:
          description: >-
            Completion timestamp in RFC 3339 format; omitted while the run is in
            flight.
          examples:
            - '2025-01-15T10:30:00Z'
          type: string
        id:
          description: Identifier of the match run.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        status:
          description: >-
            Run status. PROCESSING is in flight; COMPLETED finished
            successfully; FAILED ended in error.
          enum:
            - PROCESSING
            - COMPLETED
            - FAILED
          examples:
            - COMPLETED
          type: string
      required:
        - id
        - status
      type: object
    SetupProgressMatchRulesResponse:
      additionalProperties: false
      properties:
        total:
          description: Total number of match rules in the context.
          examples:
            - 3
          format: int64
          type: integer
      required:
        - total
      type: object
    SetupProgressReadinessResponse:
      additionalProperties: false
      properties:
        missing:
          description: >-
            Stable slugs of missing requirements (sources_left, sources_right,
            field_maps, match_rules); empty when ready.
          examples:
            - - sources_left
              - match_rules
          items:
            type: string
          type:
            - array
            - 'null'
        ready:
          description: True when the context satisfies every activation requirement.
          examples:
            - true
          type: boolean
      required:
        - ready
        - missing
      type: object
    SetupProgressResponse:
      additionalProperties: false
      properties:
        contextId:
          description: Identifier of the context this progress report describes.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        fieldMaps:
          $ref: '#/components/schemas/SetupProgressFieldMapsResponse'
          description: Field-map coverage across the context's sources.
        lastRun:
          $ref: '#/components/schemas/SetupProgressLastRunResponse'
          description: Most recent match run; null when the context has never run.
        matchRules:
          $ref: '#/components/schemas/SetupProgressMatchRulesResponse'
          description: Match-rule count for the context.
        readiness:
          $ref: '#/components/schemas/SetupProgressReadinessResponse'
          description: Activation readiness summary.
        schedules:
          $ref: '#/components/schemas/SetupProgressSchedulesResponse'
          description: Schedule count for the context.
        sources:
          $ref: '#/components/schemas/SetupProgressSourcesResponse'
          description: Source counts split by matching side.
        status:
          description: >-
            Current context lifecycle status. DRAFT is being configured; ACTIVE
            runs; PAUSED is suspended; ARCHIVED is retired.
          enum:
            - DRAFT
            - ACTIVE
            - PAUSED
            - ARCHIVED
          examples:
            - DRAFT
          type: string
      required:
        - contextId
        - status
        - sources
        - fieldMaps
        - matchRules
        - schedules
        - lastRun
        - readiness
      type: object
    SetupProgressSchedulesResponse:
      additionalProperties: false
      properties:
        total:
          description: Total number of schedules in the context.
          examples:
            - 1
          format: int64
          type: integer
      required:
        - total
      type: object
    SetupProgressSourcesResponse:
      additionalProperties: false
      properties:
        left:
          description: Number of LEFT-side sources.
          examples:
            - 1
          format: int64
          type: integer
        right:
          description: Number of RIGHT-side sources.
          examples:
            - 1
          format: int64
          type: integer
        total:
          description: Total number of sources in the context.
          examples:
            - 2
          format: int64
          type: integer
      required:
        - total
        - left
        - right
      type: object
    SimulateMatchPairResponse:
      additionalProperties: false
      properties:
        amountDelta:
          description: right.amount - left.amount as a signed decimal string
          examples:
            - '0.00'
          type: string
        dateDeltaDays:
          description: Signed whole-day difference (right - left) in UTC days
          examples:
            - 0
          format: int64
          type: integer
        left:
          $ref: '#/components/schemas/CandidateTransactionView'
          description: Left-pool transaction (the rule's left side) the pair would group
        right:
          $ref: '#/components/schemas/CandidateTransactionView'
          description: Right-pool transaction (the rule's right side) the pair would group
        score:
          description: Engine confidence score for this pair (0..100)
          examples:
            - 90
          format: int64
          maximum: 100
          minimum: 0
          type: integer
        why:
          $ref: '#/components/schemas/CandidateWhy'
          description: Per-component rationale for the score
      required:
        - left
        - right
        - score
        - why
        - amountDelta
        - dateDeltaDays
      type: object
    SimulateMatchRequest:
      additionalProperties: false
      properties:
        contextId:
          description: Context ID whose transactions the rule is simulated against
          format: uuid
          type: string
        rule:
          $ref: '#/components/schemas/SimulateRuleDefinition'
          description: Inline candidate rule to preview. Provide this OR ruleId, not both.
        ruleId:
          description: >-
            Identifier of an existing configured rule to preview. Provide this
            OR rule, not both.
          format: uuid
          type: string
        sampleLimit:
          default: 25
          description: Maximum number of would-match pairs to return in the sample
          format: int64
          maximum: 200
          minimum: 1
          type: integer
      required:
        - contextId
      type: object
    SimulateMatchResponse:
      additionalProperties: false
      properties:
        matchedGroups:
          description: Number of 1:1 groups the rule would form across the context
          examples:
            - 12
          format: int64
          minimum: 0
          type: integer
        ruleId:
          description: >-
            Identifier of the previewed rule. Empty for an inline candidate rule
            (not persisted).
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        ruleType:
          description: Strategy of the previewed rule
          examples:
            - EXACT
          type: string
        sample:
          description: Bounded sample of would-match pairs (highest score first)
          items:
            $ref: '#/components/schemas/SimulateMatchPairResponse'
          maxItems: 200
          type:
            - array
            - 'null'
        sampleTruncated:
          description: Whether matchedGroups exceeds the returned sample length
          examples:
            - false
          type: boolean
        unmatchedLeft:
          description: Left-side transactions that would remain unmatched
          examples:
            - 3
          format: int64
          minimum: 0
          type: integer
        unmatchedRight:
          description: Right-side transactions that would remain unmatched
          examples:
            - 5
          format: int64
          minimum: 0
          type: integer
      required:
        - ruleType
        - matchedGroups
        - unmatchedLeft
        - unmatchedRight
        - sampleTruncated
        - sample
      type: object
    SimulateRuleDefinition:
      additionalProperties: false
      properties:
        config:
          additionalProperties: {}
          description: >-
            Rule configuration, same shape as a stored match rule's config (e.g.
            matchAmount, matchCurrency, tolerance settings)
          type: object
        type:
          description: Rule strategy of the inline candidate rule
          examples:
            - EXACT
          type: string
      required:
        - type
        - config
      type: object
    SourceBindingResponse:
      additionalProperties: false
      properties:
        connectionId:
          description: >-
            Query-rail engine connection reference (UUID). Omitted for file-rail
            bindings.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        contextId:
          description: Identifier of the context this binding belongs to.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        createdAt:
          description: Creation timestamp in RFC 3339 format.
          examples:
            - '2025-01-15T10:30:00Z'
          type: string
        enabled:
          description: Whether the binding runs.
          examples:
            - true
          type: boolean
        format:
          description: >-
            Declared format the binding produces, as a region/family-namespaced
            descriptor key.
          examples:
            - br/cnab400/default
          type: string
        id:
          description: Unique identifier of the binding.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        kind:
          description: >-
            Rail the source is pulled on. file fetches files via a transport;
            query pulls rows through a discovery-engine connection.
          enum:
            - file
            - query
          examples:
            - file
          type: string
        scheduleSpec:
          description: >-
            Interval schedule spec the binding scheduler reads (cron or @every
            duration).
          examples:
            - '@every 1h'
          type: string
        sourceId:
          description: Identifier of the source this binding belongs to.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        transportConfig:
          $ref: '#/components/schemas/SourceBindingTransportConfigResponse'
          description: File-rail transport configuration. Omitted for query-rail bindings.
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - '2025-01-15T10:30:00Z'
          type: string
      required:
        - id
        - contextId
        - sourceId
        - kind
        - format
        - scheduleSpec
        - enabled
        - createdAt
        - updatedAt
      type: object
    SourceBindingTransportConfigRequest:
      additionalProperties: false
      properties:
        connectOptions:
          additionalProperties:
            type: string
          description: Non-secret transport tuning options (adapter-specific).
          type: object
        credentialRef:
          description: >-
            Reference to a stored credential resolved at fetch time. This is a
            reference, never the secret material itself.
          examples:
            - cred-bank-sftp
          maxLength: 255
          type: string
        glob:
          description: Optional glob filter applied within the path.
          examples:
            - '*.csv'
          maxLength: 255
          type: string
        host:
          description: Remote endpoint hostname or IP.
          examples:
            - sftp.bank.example.com
          maxLength: 255
          type: string
        kind:
          description: >-
            Transport adapter kind. sftp pulls over SFTP; https over HTTP(S); s3
            from an S3 bucket; imap from an email mailbox.
          enum:
            - sftp
            - https
            - s3
            - imap
          examples:
            - sftp
          type: string
        path:
          description: Remote directory to list and fetch from.
          examples:
            - /statements
          maxLength: 1024
          type: string
        port:
          description: Remote endpoint port.
          examples:
            - 22
          format: int64
          maximum: 65535
          minimum: 1
          type: integer
      required:
        - kind
        - host
      type: object
    SourceBindingTransportConfigResponse:
      additionalProperties: false
      properties:
        connectOptions:
          additionalProperties:
            type: string
          description: Non-secret transport tuning options (adapter-specific).
          type: object
        credentialRef:
          description: >-
            Reference to a stored credential resolved at fetch time. This is a
            reference, never the secret material itself.
          examples:
            - cred-bank-sftp
          type: string
        glob:
          description: Optional glob filter applied within the path.
          examples:
            - '*.csv'
          type: string
        host:
          description: Remote endpoint hostname or IP.
          examples:
            - sftp.bank.example.com
          type: string
        kind:
          description: >-
            Transport adapter kind. sftp pulls over SFTP; https over HTTP(S); s3
            from an S3 bucket; imap from an email mailbox.
          enum:
            - sftp
            - https
            - s3
            - imap
          examples:
            - sftp
          type: string
        path:
          description: Remote directory to list and fetch from.
          examples:
            - /statements
          type: string
        port:
          description: Remote endpoint port.
          examples:
            - 22
          format: int64
          type: integer
      required:
        - kind
        - host
      type: object
    SuggestRulesResponse:
      additionalProperties: false
      properties:
        count:
          description: Number of suggestion reviews produced
          examples:
            - 2
          format: int64
          type: integer
        items:
          description: >-
            Newly created PENDING_REVIEW suggestion reviews; producing them
            creates no rule
          items:
            $ref: '#/components/schemas/RuleSuggestionResponse'
          type:
            - array
            - 'null'
      required:
        - items
        - count
      type: object
    TestAggregatorConnectionRequest:
      additionalProperties: false
      properties:
        configName:
          description: >-
            Config name of the existing aggregator connection to test
            (tenant-scoped)
          examples:
            - pluggy-main
          minLength: 1
          type: string
        vendor:
          description: 'Aggregator vendor: pluggy or belvo'
          enum:
            - pluggy
            - belvo
          examples:
            - pluggy
          type: string
      required:
        - vendor
        - configName
      type: object
    TestAggregatorConnectionResponse:
      additionalProperties: false
      properties:
        configName:
          description: Connection config name that was tested
          examples:
            - pluggy-main
          type: string
        healthy:
          description: >-
            Whether the live connectivity check passed with the sealed
            credential
          examples:
            - true
          type: boolean
        vendor:
          description: Aggregator vendor the tested connection is bound to
          enum:
            - pluggy
            - belvo
          examples:
            - pluggy
          type: string
      required:
        - vendor
        - configName
        - healthy
      type: object
    UpdateAggregatorConnectionRequest:
      additionalProperties: false
      properties:
        accountRef:
          description: >-
            Opaque vendor account reference (Pluggy itemId, Belvo link id) the
            webhook pull threads onto its request
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          minLength: 1
          type: string
        baseUrl:
          description: Vendor API base URL, stored as the connection host
          examples:
            - https://api.pluggy.ai
          format: uri
          minLength: 1
          type: string
        clientId:
          description: >-
            Aggregator API client id (optional; supply with secret to rotate,
            omit both to keep the stored credential; sealed; never emitted)
          type: string
        configName:
          description: >-
            Unique connection config name (tenant-scoped); the mint endpoint
            binds a token to this name
          examples:
            - pluggy-main
          minLength: 1
          type: string
        secret:
          description: >-
            Aggregator API client secret (optional; supply with clientId to
            rotate, omit both to keep the stored credential; sealed; never
            emitted)
          type: string
      required:
        - configName
        - baseUrl
        - accountRef
      type: object
    UpdateSourceBindingRequest:
      additionalProperties: false
      properties:
        connectionId:
          description: >-
            Query-rail engine connection reference (UUID). Applies only to
            query-rail bindings.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        enabled:
          description: Whether the binding runs.
          examples:
            - false
          type: boolean
        format:
          description: >-
            Declared format the binding produces, as a region/family-namespaced
            descriptor key. The rail (kind) is immutable on update.
          examples:
            - br/cnab400/default
          maxLength: 255
          type: string
        scheduleSpec:
          description: >-
            Interval schedule spec the binding scheduler reads (cron or @every
            duration).
          examples:
            - '@every 30m'
          maxLength: 100
          type: string
        transportConfig:
          $ref: '#/components/schemas/SourceBindingTransportConfigRequest'
          description: >-
            File-rail transport configuration. Applies only to file-rail
            bindings.
      type: object
  examples:
    ErrorM0001:
      summary: Bad Request
      value:
        code: MTCH-0001
        title: Bad Request
        message: >-
          The request contains invalid parameters or malformed syntax. Please
          check your request and try again.
    ErrorM0002:
      summary: Internal Server Error
      value:
        code: MTCH-0002
        title: Internal Server Error
        message: internal server error
    ErrorM0101:
      summary: Token Missing
      value:
        code: MTCH-0003
        title: Unauthorized
        message: >-
          No authentication token was provided. Please include a valid Bearer
          token in the Authorization header.
    ErrorM0102:
      summary: Invalid Token
      value:
        code: MTCH-0003
        title: Unauthorized
        message: >-
          The provided token is expired, invalid, or malformed. Please provide a
          valid token and try again.
    ErrorM0103:
      summary: Insufficient Privileges
      value:
        code: MTCH-0004
        title: Forbidden
        message: >-
          You do not have the necessary permissions to perform this action.
          Please contact your administrator if you believe this is an error.
    ErrorM0201:
      summary: Context Not Found
      value:
        code: MTCH-0110
        title: Not Found
        message: context not found
    ErrorM0202:
      summary: Context Name Conflict
      value:
        code: MTCH-0101
        title: Conflict
        message: >-
          A reconciliation context with this name already exists. Please use a
          different name.
    ErrorM0203:
      summary: Invalid Context Status
      value:
        code: MTCH-0103
        title: Conflict
        message: >-
          The context status transition is not allowed. Please check the current
          status and valid transitions.
    ErrorM0204:
      summary: Context Has Active Runs
      value:
        code: MTCH-0007
        title: Conflict
        message: >-
          Cannot modify or delete this context because it has active match runs.
          Please wait for runs to complete or cancel them first.
    ErrorFeeScheduleInUse:
      summary: Fee Schedule In Use
      value:
        code: MTCH-0101
        title: Conflict
        message: >-
          Cannot delete this fee schedule because it is currently in use. Please
          detach it from all associated resources before deleting.
    ErrorExceptionCallbackInUse:
      summary: Exception Already Resolved
      value:
        code: MTCH-0103
        title: Conflict
        message: >-
          Cannot process the callback because the exception is not in a state
          that accepts callbacks. It may have already been resolved or
          cancelled.
    ErrorM0205:
      summary: Source Not Found
      value:
        code: MTCH-0111
        title: Not Found
        message: source not found
    ErrorM0206:
      summary: Source Name Conflict
      value:
        code: MTCH-0007
        title: Conflict
        message: >-
          A data source with this name already exists in the context. Please use
          a different name.
    ErrorM0207:
      summary: Invalid Source Configuration
      value:
        code: MTCH-0001
        title: Bad Request
        message: >-
          The source configuration is invalid. Please check the field mappings
          and connection settings.
    ErrorM0208:
      summary: Rule Not Found
      value:
        code: MTCH-0113
        title: Not Found
        message: rule not found
    ErrorM0209:
      summary: Rule Name Conflict
      value:
        code: MTCH-0007
        title: Conflict
        message: >-
          A match rule with this name already exists in the context. Please use
          a different name.
    ErrorM0210:
      summary: Invalid Rule Configuration
      value:
        code: MTCH-0001
        title: Bad Request
        message: >-
          The rule configuration is invalid. Please check the matching criteria
          and tolerance settings.
    ErrorM0301:
      summary: Job Not Found
      value:
        code: MTCH-0306
        title: Not Found
        message: job not found
    ErrorM0302:
      summary: Job Already Running
      value:
        code: MTCH-0305
        title: Conflict
        message: >-
          An ingestion job is already running for this source. Please wait for
          it to complete before starting a new one.
    ErrorM0303:
      summary: Invalid File Format
      value:
        code: MTCH-0303
        title: Bad Request
        message: >-
          The uploaded file format is not supported. Please upload a valid CSV,
          JSON, or Excel file.
    ErrorM0304:
      summary: File Processing Error
      value:
        code: MTCH-0001
        title: Bad Request
        message: >-
          An error occurred while processing the file. Please check the file
          content and format.
    ErrorM0305:
      summary: Transaction Not Found
      value:
        code: MTCH-0005
        title: Not Found
        message: transaction not found
    ErrorM0306:
      summary: Duplicate Transaction
      value:
        code: MTCH-0007
        title: Conflict
        message: >-
          A transaction with this external ID already exists. Duplicate
          transactions are not allowed.
    ErrorM0401:
      summary: Match Run Not Found
      value:
        code: MTCH-0005
        title: Not Found
        message: match run not found
    ErrorM0402:
      summary: Match Group Not Found
      value:
        code: MTCH-0005
        title: Not Found
        message: match group not found
    ErrorM0403:
      summary: Run Already In Progress
      value:
        code: MTCH-0408
        title: Conflict
        message: >-
          A match run is already in progress for this context. Please wait for
          it to complete before starting a new one.
    ErrorM0404:
      summary: No Transactions To Match
      value:
        code: MTCH-0001
        title: Bad Request
        message: >-
          No unmatched transactions were found for matching. Please ingest
          transactions before running the match process.
    ErrorM0405:
      summary: Invalid Match Action
      value:
        code: MTCH-0001
        title: Bad Request
        message: >-
          The requested action on the match group is not allowed in its current
          state.
    ErrorM0406:
      summary: Match Item Not Found
      value:
        code: MTCH-0005
        title: Not Found
        message: match item not found
    ErrorM0501:
      summary: Exception Not Found
      value:
        code: MTCH-0501
        title: Not Found
        message: exception not found
    ErrorM0502:
      summary: Exception Already Resolved
      value:
        code: MTCH-0503
        title: Unprocessable Entity
        message: This exception has already been resolved and cannot be modified.
    ErrorM0503:
      summary: Invalid Exception Status
      value:
        code: MTCH-0503
        title: Unprocessable Entity
        message: >-
          The exception status transition is not allowed. Please check the
          current status and valid transitions.
    ErrorM0504:
      summary: Exception Resolution Required
      value:
        code: MTCH-0001
        title: Bad Request
        message: A resolution reason is required when resolving an exception.
    ErrorM0601:
      summary: Report Not Found
      value:
        code: MTCH-0005
        title: Not Found
        message: report not found
    ErrorM0602:
      summary: Report Generation Failed
      value:
        code: MTCH-0002
        title: Internal Server Error
        message: internal server error
    ErrorM0603:
      summary: Invalid Date Range
      value:
        code: MTCH-0001
        title: Bad Request
        message: The date range is invalid. The end date must be after the start date.
    ErrorM0604:
      summary: Export Format Not Supported
      value:
        code: MTCH-0705
        title: Bad Request
        message: >-
          The requested export format is not supported. Supported formats are:
          CSV, JSON, PDF, Excel.
    ErrorM0701:
      summary: Rate Limit Exceeded
      value:
        code: MTCH-0009
        title: Too Many Requests
        message: Rate limit exceeded.
    ErrorM0702:
      summary: Export Worker Unavailable
      value:
        code: MTCH-0702
        title: Service Unavailable
        message: The export worker is currently unavailable.
    ErrorM0703:
      summary: Storage Unavailable
      value:
        code: MTCH-0703
        title: Service Unavailable
        message: The storage service is currently unavailable. Please try again later.
    ErrorM0801:
      summary: File Too Large
      value:
        code: MTCH-0010
        title: Request Entity Too Large
        message: The uploaded file exceeds the maximum allowed size.