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: 5.0.4
  license:
    name: Lerian Studio General 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.
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: Filter by context type
          explode: false
          in: query
          name: type
          schema:
            description: Filter by context type
            enum:
              - "1:1"
              - 1:N
              - N:M
            type: string
        - description: Filter by context status
          explode: false
          in: query
          name: status
          schema:
            description: Filter by context status
            enum:
              - DRAFT
              - ACTIVE
              - PAUSED
              - ARCHIVED
            type: string
      responses:
        "200":
          description: List of contexts with cursor pagination
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListContextsResponse"
        "400":
          description: Invalid query parameters
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List reconciliation contexts
      tags:
        - Configuration Contexts
      x-mint:
        href: /pt/reference/products/matcher/list-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/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateContextRequest"
        description: Context creation payload
        required: true
      responses:
        "201":
          description: |-
            Successfully created context.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationContextResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-context-payload:
                  $ref: "#/components/examples/400-invalid-context-payload"
                mtch-0001-context-name-is-required:
                  $ref: "#/components/examples/mtch-0001-context-name-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: A context with this name already exists, or two rules share a priority.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0101-a-reconciliation-context-with-this-name-already-exists:
                  $ref: "#/components/examples/mtch-0101-a-reconciliation-context-with-this-name-already-exists"
                mtch-0102-priority-already-exists-in-context:
                  $ref: "#/components/examples/mtch-0102-priority-already-exists-in-context--post-v1-contexts"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create a reconciliation context
      tags:
        - Configuration Contexts
      x-mint:
        href: /pt/reference/products/matcher/create-context
  /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:
            description: Context ID
            format: uuid
            type: string
      responses:
        "200":
          description: Successfully retrieved context
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationContextResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a reconciliation context
      tags:
        - Configuration Contexts
      x-mint:
        href: /pt/reference/products/matcher/retrieve-context
    patch:
      description: "Use this endpoint to update the fields of a specific reconciliation context by its identifier. Setting `status` to `ACTIVE` is refused with `409` while the context is not ready for activation. A `signConvention` change is refused with `409` once the context has carried a partial balance, or while a match run is in progress."
      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:
            description: Context ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateContextRequest"
        description: Context updates
        required: true
      responses:
        "200":
          description: |-
            Successfully updated context.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationContextResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0001-context-name-is-required:
                  $ref: "#/components/examples/mtch-0001-context-name-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "409":
          description: The request conflicts with the current state of the context.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0101-a-reconciliation-context-with-this-name-already-exists:
                  $ref: "#/components/examples/mtch-0101-a-reconciliation-context-with-this-name-already-exists--patch-v1-contexts-contextid"
                mtch-0103-cannot-pause-context-in-draft-status-invalid-state-transitio:
                  $ref: "#/components/examples/mtch-0103-cannot-pause-context-in-draft-status-invalid-state-transitio"
                mtch-0104-archived-context-cannot-be-modified:
                  $ref: "#/components/examples/mtch-0104-archived-context-cannot-be-modified"
                mtch-0103-context-is-not-ready-for-activation:
                  $ref: '#/components/examples/mtch-0103-context-is-not-ready-for-activation'
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Update a reconciliation context
      tags:
        - Configuration Contexts
      x-mint:
        href: /pt/reference/products/matcher/update-context
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0103-cannot-archive-context-in-archived-status-invalid-state-tran:
                  $ref: "#/components/examples/mtch-0103-cannot-archive-context-in-archived-status-invalid-state-tran"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Archive a reconciliation context
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/archive-context
  /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
        - description: The unique identifier of the reconciliation context to clone.
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CloneContextRequest"
        description: Clone context payload
        required: true
      responses:
        "201":
          description: |-
            Successfully cloned context.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0109-new-context-name-is-required-for-clone:
                  $ref: "#/components/examples/mtch-0109-new-context-name-is-required-for-clone"
                mtch-0001-build-cloned-context-entity-context-name-exceeds-100-charact:
                  $ref: "#/components/examples/mtch-0001-build-cloned-context-entity-context-name-exceeds-100-charact"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "409":
          description: A context with this name already exists.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0101-a-context-with-this-name-already-exists:
                  $ref: "#/components/examples/mtch-0101-a-context-with-this-name-already-exists"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Clone a reconciliation context
      tags:
        - Configuration Contexts
      x-mint:
        href: /pt/reference/products/matcher/clone-context
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Pagination cursor from previous response
            type: string
        - description: The maximum number of items to include in the response.
          explode: false
          in: query
          name: limit
          schema:
            default: 20
            description: Maximum number of records to return
            format: int64
            maximum: 200
            minimum: 1
            type: integer
      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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List export jobs by context
      tags:
        - Export Jobs
      x-mint:
        href: /pt/reference/products/matcher/list-export-jobs-by-context
    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:
            description: Context ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-summary-report-type-not-supported-for-async-export:
                  $ref: "#/components/examples/400-summary-report-type-not-supported-for-async-export"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0008-internal-error:
                  $ref: "#/components/examples/mtch-0008-internal-error--post-v1-contexts-contextid-export-jobs"
      security:
        - BearerAuth: []
      summary: Create an export job
      tags:
        - Export Jobs
      x-mint:
        href: /pt/reference/products/matcher/create-export-job
  /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:
            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":
          description: List of fee rules for the context
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListFeeRulesResponse"
        "400":
          description: Invalid context ID format
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List fee rules
      tags:
        - Configuration Fee Rules
      x-mint:
        href: /pt/reference/products/matcher/list-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
        - description: The unique identifier of the reconciliation context.
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFeeRuleRequest"
        description: Fee rule creation payload
        required: true
      responses:
        "201":
          description: |-
            Successfully created fee rule.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeeRuleResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-fee-schedule-id:
                  $ref: "#/components/examples/400-invalid-fee-schedule-id"
                mtch-0001-create-fee-rule-fee-rule-count-exceeds-the-maximum-allowed-p:
                  $ref: "#/components/examples/mtch-0001-create-fee-rule-fee-rule-count-exceeds-the-maximum-allowed-p"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "409":
          description: Conflict — duplicate priority or name within this context
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0107-a-fee-rule-with-this-priority-already-exists-in-the-context:
                  $ref: "#/components/examples/mtch-0107-a-fee-rule-with-this-priority-already-exists-in-the-context"
                mtch-0101-a-fee-rule-with-this-name-already-exists-in-the-context:
                  $ref: "#/components/examples/mtch-0101-a-fee-rule-with-this-name-already-exists-in-the-context"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create a fee rule
      tags:
        - Configuration Fee Rules
      x-mint:
        href: /pt/reference/products/matcher/create-fee-rule
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List field maps for a context
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/list-context-field-maps
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0103-cannot-unarchive-context-in-active-status-invalid-state-tran:
                  $ref: "#/components/examples/mtch-0103-cannot-unarchive-context-in-active-status-invalid-state-tran"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Restore an archived reconciliation context
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/restore-context
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The maximum number of items to include in the response.
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: Filter by rule type
          explode: false
          in: query
          name: type
          schema:
            description: Filter by rule type
            enum:
              - EXACT
              - TOLERANCE
              - DATE_LAG
              - FUZZY
            type: string
      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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List match rules
      tags:
        - Configuration Match Rules
      x-mint:
        href: /pt/reference/products/matcher/list-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:
            description: Context ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateMatchRuleRequest"
        description: Match rule creation payload
        required: true
      responses:
        "201":
          description: |-
            Successfully created match rule.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatchRuleResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-match-rule-payload:
                  $ref: "#/components/examples/400-invalid-match-rule-payload"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "409":
          description: A rule with this priority already exists in the context.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0102-priority-already-exists-in-context:
                  $ref: "#/components/examples/mtch-0102-priority-already-exists-in-context"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create a match rule
      tags:
        - Configuration Match Rules
      x-mint:
        href: /pt/reference/products/matcher/create-match-rule
  /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:
            description: Context ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReorderRequest"
        description: Ordered list of rule IDs
        required: true
      responses:
        "204":
          description: |-
            Match rules reordered.
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid reorder payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-missing-rule-ids:
                  $ref: "#/components/examples/400-missing-rule-ids"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0113-match-rule-not-found:
                  $ref: "#/components/examples/mtch-0113-match-rule-not-found--post-v1-contexts-contextid-rules-reorder"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Reorder match rules
      tags:
        - Configuration Match Rules
      x-mint:
        href: /pt/reference/products/matcher/reorder-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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the match rule.
          in: path
          name: ruleId
          required: true
          schema:
            description: Rule ID
            format: uuid
            type: string
      responses:
        "204":
          description: Match rule successfully deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Match rule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0113-match-rule-not-found:
                  $ref: "#/components/examples/mtch-0113-match-rule-not-found--delete-v1-contexts-contextid-rules-ruleid"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete a match rule
      tags:
        - Configuration Match Rules
      x-mint:
        href: /pt/reference/products/matcher/delete-match-rule
    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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the match rule.
          in: path
          name: ruleId
          required: true
          schema:
            description: Rule ID
            format: uuid
            type: string
      responses:
        "200":
          description: Successfully retrieved match rule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatchRuleResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Match rule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0113-match-rule-not-found:
                  $ref: "#/components/examples/mtch-0113-match-rule-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a match rule
      tags:
        - Configuration Match Rules
      x-mint:
        href: /pt/reference/products/matcher/retrieve-match-rule
    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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the match rule.
          in: path
          name: ruleId
          required: true
          schema:
            description: Rule ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateMatchRuleRequest"
        description: Match rule updates
        required: true
      responses:
        "200":
          description: |-
            Successfully updated match rule.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatchRuleResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-match-rule-payload:
                  $ref: "#/components/examples/400-invalid-match-rule-payload--patch-v1-contexts-contextid-rules-ruleid"
                mtch-0001-config-is-required:
                  $ref: "#/components/examples/mtch-0001-config-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Match rule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0113-match-rule-not-found:
                  $ref: "#/components/examples/mtch-0113-match-rule-not-found--patch-v1-contexts-contextid-rules-ruleid"
        "409":
          description: A rule with this priority already exists in the context.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0102-priority-already-exists-in-context:
                  $ref: "#/components/examples/mtch-0102-priority-already-exists-in-context--patch-v1-contexts-contextid-rules-ruleid"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Update a match rule
      tags:
        - Configuration Match Rules
      x-mint:
        href: /pt/reference/products/matcher/update-match-rule
  /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:
            description: Context ID
            format: uuid
            type: string
      responses:
        "200":
          description: List of schedules for the context
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/ScheduleResponse"
                type:
                  - array
                  - "null"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List schedules for a context
      tags:
        - Configuration Schedules
      x-mint:
        href: /pt/reference/products/matcher/list-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:
            description: Context ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateScheduleRequest"
        description: Schedule details
        required: true
      responses:
        "201":
          description: |-
            Schedule created.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0001-create-schedule-entity-invalid-cron-expression-cannot-comput:
                  $ref: "#/components/examples/mtch-0001-create-schedule-entity-invalid-cron-expression-cannot-comput"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create a schedule
      tags:
        - Configuration Schedules
      x-mint:
        href: /pt/reference/products/matcher/create-schedule
  /v1/contexts/{contextId}/schedules/{scheduleId}:
    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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            description: Schedule ID
            format: uuid
            type: string
      responses:
        "204":
          description: Schedule deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Schedule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0116-schedule-not-found:
                  $ref: "#/components/examples/mtch-0116-schedule-not-found--delete-v1-contexts-contextid-schedules-scheduleid"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete a schedule
      tags:
        - Configuration Schedules
      x-mint:
        href: /pt/reference/products/matcher/delete-schedule
    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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            description: Schedule ID
            format: uuid
            type: string
      responses:
        "200":
          description: Schedule details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduleResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Schedule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0116-schedule-not-found:
                  $ref: "#/components/examples/mtch-0116-schedule-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a schedule
      tags:
        - Configuration Schedules
      x-mint:
        href: /pt/reference/products/matcher/retrieve-schedule
    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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the schedule.
          in: path
          name: scheduleId
          required: true
          schema:
            description: Schedule ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateScheduleRequest"
        description: Fields to update
        required: true
      responses:
        "200":
          description: |-
            Schedule updated.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0001-update-schedule-entity-invalid-cron-expression-cannot-comput:
                  $ref: "#/components/examples/mtch-0001-update-schedule-entity-invalid-cron-expression-cannot-comput"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Schedule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0116-schedule-not-found:
                  $ref: "#/components/examples/mtch-0116-schedule-not-found--patch-v1-contexts-contextid-schedules-scheduleid"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Update a schedule
      tags:
        - Configuration Schedules
      x-mint:
        href: /pt/reference/products/matcher/update-schedule
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get context setup progress
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/get-setup-progress
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The maximum number of items to include in the response.
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: Filter by source type
          explode: false
          in: query
          name: type
          schema:
            description: Filter by source type
            enum:
              - LEDGER
              - BANK
              - GATEWAY
              - CUSTOM
              - FETCHER
            type: string
        - description: When true, archived (soft-deleted) sources are included in the listing. Defaults to false (live sources only).
          explode: false
          in: query
          name: includeArchived
          schema:
            default: false
            description: When true, archived (soft-deleted) sources are included in the listing. Defaults to false (live sources only).
            type: boolean
      responses:
        "200":
          description: List of sources with cursor pagination
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListSourcesResponse"
        "400":
          description: Invalid query parameters
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List reconciliation sources
      tags:
        - Configuration Sources
      x-mint:
        href: /pt/reference/products/matcher/list-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:
            description: Context ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSourceRequest"
        description: Source creation payload
        required: true
      responses:
        "201":
          description: |-
            Successfully created source.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationSourceResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-source-payload:
                  $ref: "#/components/examples/400-invalid-source-payload"
                mtch-0001-source-name-exceeds-50-characters:
                  $ref: "#/components/examples/mtch-0001-source-name-exceeds-50-characters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create a reconciliation source
      tags:
        - Configuration Sources
      x-mint:
        href: /pt/reference/products/matcher/create-source
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
      responses:
        "200":
          description: Successfully retrieved source
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationSourceResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Source not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a reconciliation source
      tags:
        - Configuration Sources
      x-mint:
        href: /pt/reference/products/matcher/retrieve-source
    patch:
      description: Use this endpoint to update the fields of a specific reconciliation source by its identifier. A `side` change is refused with `409` once the context has carried a partial balance, or while a match run is in progress.
      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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSourceRequest"
        description: Source updates
        required: true
      responses:
        "200":
          description: |-
            Successfully updated source.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReconciliationSourceResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-source-payload:
                  $ref: "#/components/examples/400-invalid-source-payload"
                mtch-0001-source-name-exceeds-50-characters:
                  $ref: "#/components/examples/mtch-0001-source-name-exceeds-50-characters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Source not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found--patch-v1-contexts-contextid-sources-sourceid"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Update a reconciliation source
      tags:
        - Configuration Sources
      x-mint:
        href: /pt/reference/products/matcher/update-source
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found--post-v1-contexts-contextid-sources-sourceid-archive"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Archive a reconciliation source
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/archive-source
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List source bindings
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/list-source-bindings
    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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-source-binding-payload:
                  $ref: "#/components/examples/400-invalid-source-binding-payload"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found--post-v1-contexts-contextid-sources-sourceid-bindings"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create a source binding
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/create-source-binding
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found--delete-v1-contexts-contextid-sources-sourceid-bindings-bindingid"
                mtch-0005-source-binding-not-found:
                  $ref: "#/components/examples/mtch-0005-source-binding-not-found--delete-v1-contexts-contextid-sources-sourceid-bindings-bindingid"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete a source binding
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/delete-source-binding
    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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found"
                mtch-0005-source-binding-not-found:
                  $ref: "#/components/examples/mtch-0005-source-binding-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a source binding
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/get-source-binding
    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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-source-binding-payload:
                  $ref: "#/components/examples/400-invalid-source-binding-payload--patch-v1-contexts-contextid-sources-sourceid-bindings-bindingid"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found--patch-v1-contexts-contextid-sources-sourceid-bindings-bindingid"
                mtch-0005-source-binding-not-found:
                  $ref: "#/components/examples/mtch-0005-source-binding-not-found--patch-v1-contexts-contextid-sources-sourceid-bindings-bindingid"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Update a source binding
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/update-source-binding
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
      responses:
        "200":
          description: Successfully retrieved field map
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldMapResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Field map not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found"
                mtch-0112-field-map-not-found:
                  $ref: "#/components/examples/mtch-0112-field-map-not-found--get-v1-contexts-contextid-sources-sourceid-field-maps"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a field map by source
      tags:
        - Configuration Field Maps
      x-mint:
        href: /pt/reference/products/matcher/retrieve-field-map-by-source
    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. A source holds at most one field map: a second create is refused with `409`, so update the existing map instead."
      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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFieldMapRequest"
        description: Field map creation payload
        required: true
      responses:
        "201":
          description: |-
            Successfully created field map.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldMapResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0001-invalid-field-map-mapping-missing-required-keys-amount:
                  $ref: "#/components/examples/mtch-0001-invalid-field-map-mapping-missing-required-keys-amount"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Context or source not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found--post-v1-contexts-contextid-sources-sourceid-field-maps"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create a field map
      tags:
        - Configuration Field Maps
      x-mint:
        href: /pt/reference/products/matcher/create-field-map
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0110-context-not-found:
                  $ref: "#/components/examples/mtch-0110-context-not-found"
                mtch-0111-source-not-found:
                  $ref: "#/components/examples/mtch-0111-source-not-found--post-v1-contexts-contextid-sources-sourceid-restore"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Restore an archived reconciliation source
      tags:
        - Configuration
      x-mint:
        href: /pt/reference/products/matcher/restore-source
  /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. Each row carries `testable`, which tells whether the connectivity test can run for that connection.'
      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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List aggregator connections
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/list-aggregator-connections
    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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-validation-failed:
                  $ref: "#/components/examples/400-validation-failed"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0007-aggregator-connection-already-exists:
                  $ref: "#/components/examples/mtch-0007-aggregator-connection-already-exists"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create aggregator connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/create-aggregator-connection
  /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 configName. The vendor is read from the stored connection, not from the request. No credential is supplied or returned: the result is the secret-free boolean health of the connection. A config name that matches no connection returns `404`; a connection whose vendor has no test path (Belvo) returns `422` (`MTCH-0210`), and no test runs.'
      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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-validation-failed:
                  $ref: "#/components/examples/400-validation-failed"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-aggregator-connection-not-found:
                  $ref: "#/components/examples/mtch-0005-aggregator-connection-not-found--post-v1-discovery-aggregator-connections-test"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Test aggregator connection credentials
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/test-aggregator-connection
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-aggregator-connection-not-found:
                  $ref: "#/components/examples/mtch-0005-aggregator-connection-not-found"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete aggregator connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/delete-aggregator-connection
    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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-aggregator-connection-not-found:
                  $ref: "#/components/examples/mtch-0005-aggregator-connection-not-found"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get aggregator connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/get-aggregator-connection
    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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-clientid-and-secret-must-both-be-supplied-to-rotate-the-cred:
                  $ref: "#/components/examples/400-clientid-and-secret-must-both-be-supplied-to-rotate-the-cred"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-aggregator-connection-not-found:
                  $ref: "#/components/examples/mtch-0005-aggregator-connection-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Update aggregator connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/update-aggregator-connection
  /v1/discovery/aggregator-connections/{id}/connect-token:
    post:
      description: "Use this endpoint to get the consent token that the aggregator's own consent widget (Pluggy Connect or the Belvo widget) needs for this connection. The request has no body: Matcher reads the vendor from the stored connection. For a connection already bound to a vendor item or link, the token starts a re-consent. After the end customer completes the widget, bind the item or link id to the connection with an update that sets `accountRef`."
      operationId: mintAggregatorConsentToken
      parameters:
        - description: Opaque aggregator connection id
          in: path
          name: id
          required: true
          schema:
            description: Opaque aggregator connection id
            type: string
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AggregatorConsentTokenResponse"
          description: Created
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-aggregator-connection-not-found:
                  $ref: "#/components/examples/mtch-0005-aggregator-connection-not-found"
        "422":
          description: Matcher could not mint a consent token for this connection.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0213-consent-flow-not-available:
                  $ref: "#/components/examples/mtch-0213-consent-flow-not-available"
                mtch-0212-consent-token-not-issued:
                  $ref: "#/components/examples/mtch-0212-consent-token-not-issued"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Mint aggregator consent token
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/mint-aggregator-consent-token
  /v1/discovery/connections:
    get:
      description: Use this endpoint to retrieve all discovered 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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List discovered connections
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/list-discovery-connections
    post:
      description: Provisions a 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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0208-connector-type-is-not-registered-db2:
                  $ref: "#/components/examples/mtch-0208-connector-type-is-not-registered-db2"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0203-internal-error:
                  $ref: "#/components/examples/mtch-0203-internal-error"
      security:
        - BearerAuth: []
      summary: Create discovery connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/create-discovery-connection
  /v1/discovery/connections/{connectionId}:
    delete:
      description: Deletes a Matcher-owned 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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0201-connection-not-found:
                  $ref: "#/components/examples/mtch-0201-connection-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0203-internal-error:
                  $ref: "#/components/examples/mtch-0203-internal-error"
      security:
        - BearerAuth: []
      summary: Delete discovery connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/delete-discovery-connection
    get:
      description: Use this endpoint to retrieve a single discovered 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:
            description: Connection ID (UUID)
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
            format: uuid
            type: string
      responses:
        "200":
          description: Connection details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectionResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Connection not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0201-connection-not-found:
                  $ref: "#/components/examples/mtch-0201-connection-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a discovered connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/retrieve-discovery-connection
    patch:
      description: Updates a Matcher-owned 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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-at-least-one-connection-field-must-be-provided:
                  $ref: "#/components/examples/400-at-least-one-connection-field-must-be-provided"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0201-connection-not-found:
                  $ref: "#/components/examples/mtch-0201-connection-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0203-internal-error:
                  $ref: "#/components/examples/mtch-0203-internal-error"
      security:
        - BearerAuth: []
      summary: Update discovery connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/update-discovery-connection
  /v1/discovery/connections/{connectionId}/extractions:
    post:
      description: Use this endpoint to create an extraction request for a discovered connection and submit it to the extraction engine 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:
            description: Connection ID (UUID)
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0204-invalid-extraction-request-start-date-must-use-yyyy-mm-dd-fo:
                  $ref: "#/components/examples/mtch-0204-invalid-extraction-request-start-date-must-use-yyyy-mm-dd-fo"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Connection not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0201-connection-not-found:
                  $ref: "#/components/examples/mtch-0201-connection-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Start a connection extraction
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/create-extraction
  /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:
            description: Connection ID (UUID)
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
            format: uuid
            type: string
      responses:
        "200":
          description: Schema for the connection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectionSchemaResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Connection not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0201-connection-not-found:
                  $ref: "#/components/examples/mtch-0201-connection-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get connection schema
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/get-connection-schema
  /v1/discovery/connections/{connectionId}/schema/history:
    get:
      description: "Use this endpoint to list the earlier generations of a connection's schema map, oldest first. Each generation records when it stopped being the live schema map, and `retirementCause` records what Matcher observed when it retired it."
      operationId: getDiscoveryConnectionSchemaHistory
      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:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectionSchemaHistoryResponse"
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Connection not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0201-connection-not-found:
                  $ref: "#/components/examples/mtch-0201-connection-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get connection schema history
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/get-connection-schema-history
  /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:
            description: Connection ID (UUID)
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
            format: uuid
            type: string
      responses:
        "200":
          description: Test result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestConnectionResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Connection not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0201-connection-not-found:
                  $ref: "#/components/examples/mtch-0201-connection-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Test a connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/test-discovery-connection
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List connector types
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/list-discovery-connector-types
  /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:
            description: Extraction ID (UUID)
            examples:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
            format: uuid
            type: string
      responses:
        "200":
          description: Extraction request details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExtractionRequestResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Extraction not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0202-extraction-not-found:
                  $ref: "#/components/examples/mtch-0202-extraction-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get an extraction request
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/retrieve-extraction
  /v1/discovery/refresh:
    post:
      description: Use this endpoint to force an immediate sync with the extraction engine, 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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: A refresh is already in progress
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0205-discovery-refresh-already-in-progress:
                  $ref: "#/components/examples/mtch-0205-discovery-refresh-already-in-progress"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Refresh discovery
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/refresh-discovery
  /v1/discovery/rest-connections:
    post:
      description: "Use this endpoint to create a REST connection to a payment provider: PagBank, Stripe, or Pix BCB. The credential fields each connector type requires are listed as `requiredFields` on GET /v1/discovery/connector-types. An optional `baseURL` replaces the default provider address for this connection. After you create it, the connection appears in GET /v1/discovery/connections; an update to a REST connection accepts only `configName`."
      operationId: createRESTDiscoveryConnection
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RESTConnectionRequest"
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConnectionResponse"
          description: Created
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0001-rest-credential-field-is-required:
                  $ref: "#/components/examples/mtch-0001-rest-credential-field-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0203-internal-error:
                  $ref: "#/components/examples/mtch-0203-internal-error"
      security:
        - BearerAuth: []
      summary: Create REST discovery connection
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/create-rest-discovery-connection
  /v1/discovery/status:
    get:
      description: Use this endpoint to retrieve the current discovery status, including 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":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get discovery status
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/discovery-status
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-connection-config-name-is-required:
                  $ref: "#/components/examples/400-connection-config-name-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0201-no-aggregator-connection-for-the-given-config-name:
                  $ref: "#/components/examples/mtch-0201-no-aggregator-connection-for-the-given-config-name"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Mint an aggregator webhook token
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/mint-aggregator-webhook-token
  /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:
        "200":
          description: The event was already processed. Matcher acknowledges it and does not process it again.
        '202':
          description: Accepted
        "400":
          description: The webhook body is not a recognized event.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-bad-request:
                  $ref: "#/components/examples/400-bad-request"
        "401":
          description: The webhook source could not be verified.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                401-unauthorized:
                  $ref: "#/components/examples/401-unauthorized"
        "404":
          description: The provider or the webhook token is not recognized.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                404-no-detail:
                  $ref: "#/components/examples/404-no-detail"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                503-internal-error:
                  $ref: "#/components/examples/503-internal-error--post-v1-discovery-webhooks-provider-webhooktoken"
      security:
        - {}
        - WebhookSignature: []
      summary: Receive an aggregator webhook
      tags:
        - Discovery
      x-mint:
        href: /pt/reference/products/matcher/receive-aggregator-webhook
  /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: Filter by dispute state
          explode: false
          in: query
          name: state
          schema:
            description: Filter by state
            enum:
              - DRAFT
              - OPEN
              - PENDING_EVIDENCE
              - WON
              - LOST
            type: string
        - description: Filter by dispute category
          explode: false
          in: query
          name: category
          schema:
            description: Filter by category
            enum:
              - BANK_FEE_ERROR
              - UNRECOGNIZED_CHARGE
              - DUPLICATE_TRANSACTION
              - OTHER
            type: string
        - description: Start date filter (RFC 3339 format)
          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: End date filter (RFC 3339 format)
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: The maximum number of items to include in the response.
          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: Sort by field
          explode: false
          in: query
          name: sort_by
          schema:
            description: Sort by field
            enum:
              - id
              - created_at
              - updated_at
              - state
              - category
            type: string
        - description: Sort order
          explode: false
          in: query
          name: sort_order
          schema:
            description: Sort order
            enum:
              - asc
              - desc
            type: string
      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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-filter-parameters:
                  $ref: "#/components/examples/400-invalid-filter-parameters--get-v1-disputes"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List disputes
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/list-disputes
  /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:
            description: Dispute ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440001
            format: uuid
            type: string
      responses:
        "200":
          description: Successfully retrieved dispute
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DisputeResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Dispute not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0502-dispute-not-found:
                  $ref: "#/components/examples/mtch-0502-dispute-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a dispute
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/retrieve-dispute
  /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
        - description: Dispute ID
          in: path
          name: disputeId
          required: true
          schema:
            description: Dispute ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440001
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-dispute-resolution-is-required:
                  $ref: "#/components/examples/400-dispute-resolution-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0502-dispute-not-found:
                  $ref: "#/components/examples/mtch-0502-dispute-not-found"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0006-win-dispute-invalid-dispute-transition:
                  $ref: "#/components/examples/mtch-0006-win-dispute-invalid-dispute-transition"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Close a dispute
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/close-dispute
  /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
        - description: Dispute ID
          in: path
          name: disputeId
          required: true
          schema:
            description: Dispute ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440001
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-evidence-comment-is-required:
                  $ref: "#/components/examples/400-evidence-comment-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0502-dispute-not-found:
                  $ref: "#/components/examples/mtch-0502-dispute-not-found"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0006-add-evidence-cannot-add-evidence-in-current-state:
                  $ref: "#/components/examples/mtch-0006-add-evidence-cannot-add-evidence-in-current-state"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Submit evidence to a dispute
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/submit-evidence
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-evidence-comment-is-required:
                  $ref: "#/components/examples/400-evidence-comment-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0502-dispute-not-found:
                  $ref: "#/components/examples/mtch-0502-dispute-not-found"
        "413":
          description: The file is larger than 10 MiB.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                413-request-body-is-too-large-limit-10485760-bytes:
                  $ref: "#/components/examples/413-request-body-is-too-large-limit-10485760-bytes"
        "415":
          description: The `Content-Type` header is not `application/pdf`, `image/png`, `image/jpeg`, or `text/csv`.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                415-evidence-file-content-type-is-not-supported:
                  $ref: "#/components/examples/415-evidence-file-content-type-is-not-supported"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0006-add-evidence-cannot-add-evidence-in-current-state:
                  $ref: "#/components/examples/mtch-0006-add-evidence-cannot-add-evidence-in-current-state"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0019-internal-error:
                  $ref: "#/components/examples/mtch-0019-internal-error"
      security:
        - BearerAuth: []
      summary: Upload an evidence file to a dispute
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/upload-evidence
  /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 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 to the exceptions a specific match run surfaced (UUID). Each exception records the LATEST run that touched it, so this returns the breaks that run produced. Legacy rows written before run linkage, and ingestion-minted duplicate-transaction breaks, carry no run id and never match. Absent leaves the listing unfiltered by run.
          explode: false
          in: query
          name: run_id
          schema:
            description: Filter to the exceptions a specific match run surfaced (UUID). Each exception records the LATEST run that touched it, so this returns the breaks that run produced. Legacy rows written before run linkage, and ingestion-minted duplicate-transaction breaks, carry no run id and never match. Absent leaves the listing unfiltered by run.
            examples:
              - 550e8400-e29b-41d4-a716-446655440002
            format: uuid
            type: string
        - description: Filter by status
          explode: false
          in: query
          name: status
          schema:
            description: Filter by status
            enum:
              - OPEN
              - ASSIGNED
              - PENDING_RESOLUTION
              - 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:
              - "550e8400"
            type: string
        - description: Filter from date (RFC3339)
          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 (RFC3339)
          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). Surfaces aged open-item breaks. 0 (default) disables the filter. Sort by created_at ascending to order oldest-first.
          explode: false
          in: query
          name: min_age_days
          schema:
            description: Filter to exceptions at least this many days old (by created_at). Surfaces aged open-item breaks. 0 (default) disables the filter. Sort by created_at ascending to order oldest-first.
            examples:
              - 30
            format: int64
            maximum: 3650
            minimum: 0
            type: integer
        - description: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: Number of items per page
          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: "The field used to sort the results."
          explode: false
          in: query
          name: sort_by
          schema:
            description: "Sort by field. When both sort_by and sort_order are omitted, results use the default queue ordering: status ASC (OPEN, ASSIGNED, PENDING_RESOLUTION, RESOLVED), then created_at DESC, then id DESC. Cursors are bound to the ordering that minted them; switching sort parameters mid-pagination returns 400."
            enum:
              - id
              - created_at
              - updated_at
              - severity
              - status
            type: string
        - description: The order used to sort the results.
          explode: false
          in: query
          name: sort_order
          schema:
            description: Sort order (engages the explicit single-column sort, by id when sort_by is omitted)
            enum:
              - asc
              - desc
            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/ListExceptionsResponse"
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-filter-parameters:
                  $ref: "#/components/examples/400-invalid-filter-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List exceptions
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/list-exceptions
  /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/XIdempotency"
      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).
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-exception-id:
                  $ref: "#/components/examples/400-invalid-exception-id"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Bulk assign exceptions
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/bulk-assign-exceptions
  /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/XIdempotency"
      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).
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-exception-id:
                  $ref: "#/components/examples/400-invalid-exception-id--post-v1-exceptions-bulk-dispatch"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Bulk dispatch exceptions
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/bulk-dispatch-exceptions
  /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/XIdempotency"
      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).
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-exception-id:
                  $ref: "#/components/examples/400-invalid-exception-id--post-v1-exceptions-bulk-resolve"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Bulk resolve exceptions
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/bulk-resolve-exceptions
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List callback credentials
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/list-callback-credentials
    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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-validation-failed:
                  $ref: "#/components/examples/400-validation-failed"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Mint a callback credential
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/mint-callback-credential
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-callback-credential-not-found:
                  $ref: "#/components/examples/mtch-0005-callback-credential-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Revoke a callback credential
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/revoke-callback-credential
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-callback-credential-not-found:
                  $ref: "#/components/examples/mtch-0005-callback-credential-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Rotate a callback credential
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/rotate-callback-credential
  /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
              - PENDING_RESOLUTION
              - 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:
              - "550e8400"
            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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-filter-parameters:
                  $ref: "#/components/examples/400-invalid-filter-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Select exception ids by filter
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/select-exception-ids
  /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:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            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"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get exception
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/retrieve-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
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-resolution-notes-are-required:
                  $ref: "#/components/examples/400-resolution-notes-are-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0503-exception-cannot-be-resolved-in-current-state:
                  $ref: "#/components/examples/mtch-0503-exception-cannot-be-resolved-in-current-state"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Adjust entry for an exception
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/adjust-entry-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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-assignee-is-required-for-bulk-assign:
                  $ref: "#/components/examples/400-assignee-is-required-for-bulk-assign"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0503-exception-cannot-transition-in-current-state:
                  $ref: "#/components/examples/mtch-0503-exception-cannot-transition-in-current-state"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Assign an exception
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/assign-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: The unique identifier of the exception.
          in: path
          name: exceptionId
          required: true
          schema:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - description: Opaque bearer token authenticating the external system
          in: header
          name: X-Callback-Token
          required: true
          schema:
            description: Opaque bearer token authenticating the external system
            type: string
        - description: Idempotency key for deduplication
          in: header
          name: X-Idempotency
          required: true
          schema:
            description: Idempotency key for deduplication
            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.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessCallbackResponse"
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-dueat-format-expected-rfc3339:
                  $ref: "#/components/examples/400-invalid-dueat-format-expected-rfc3339"
        "404":
          description: The callback token is not recognized, or the exception does not exist.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                404-not-found:
                  $ref: "#/components/examples/404-not-found"
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0504-callback-is-already-being-processed:
                  $ref: "#/components/examples/mtch-0504-callback-is-already-being-processed"
                mtch-0505-callback-can-be-retried:
                  $ref: "#/components/examples/mtch-0505-callback-can-be-retried"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          description: The external system sent more callbacks for the tenant in the current minute than the limit allows. Wait, then retry.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0506-callback-rate-limit-exceeded:
                  $ref: "#/components/examples/mtch-0506-callback-rate-limit-exceeded"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                503-internal-error:
                  $ref: "#/components/examples/503-internal-error"
      security:
        - CallbackToken: []
      summary: Process exception callback
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/process-exception-callback
  /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:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
      responses:
        "200":
          description: List of comments for the exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListCommentsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Exception not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List exception comments
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/list-exception-comments
    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:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddCommentRequest"
        description: Comment payload
        required: true
      responses:
        "201":
          description: |-
            Comment added successfully.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-comment-content-is-required:
                  $ref: "#/components/examples/400-comment-content-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Exception not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Add a comment to an exception
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/add-exception-comment
  /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:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - description: The unique identifier of the comment.
          in: path
          name: commentId
          required: true
          schema:
            description: Comment ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440002
            format: uuid
            type: string
      responses:
        "204":
          description: Comment successfully deleted
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-comment-id-is-required:
                  $ref: "#/components/examples/400-comment-id-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or you are not the author of the comment.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0004-only-the-comment-author-can-delete-their-comment:
                  $ref: "#/components/examples/mtch-0004-only-the-comment-author-can-delete-their-comment"
        "404":
          description: Comment or exception not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
                mtch-0507-comment-not-found:
                  $ref: "#/components/examples/mtch-0507-comment-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete an exception comment
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/delete-exception-comment
  /v1/exceptions/{exceptionId}/dispatch:
    post:
      description: Use this endpoint to dispatch an exception 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
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-validation-failed:
                  $ref: "#/components/examples/400-validation-failed"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0509-connector-not-configured-for-target-system:
                  $ref: "#/components/examples/mtch-0509-connector-not-configured-for-target-system"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Dispatch exception to external system
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/dispatch-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
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-dispute-category-is-required:
                  $ref: "#/components/examples/400-dispute-category-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Open a dispute
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/open-dispute
  /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
        - description: Exception ID
          in: path
          name: exceptionId
          required: true
          schema:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-resolution-notes-are-required:
                  $ref: "#/components/examples/400-resolution-notes-are-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0503-exception-cannot-be-resolved-in-current-state:
                  $ref: "#/components/examples/mtch-0503-exception-cannot-be-resolved-in-current-state"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Force match an exception
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/force-match-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:
            description: Exception ID (UUID)
            examples:
              - 550e8400-e29b-41d4-a716-446655440000
            format: uuid
            type: string
        - description: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: Number of items per page
          explode: false
          in: query
          name: limit
          schema:
            default: 20
            description: Maximum number of records to return
            format: int64
            maximum: 200
            minimum: 1
            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/HistoryResponse"
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get exception history
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/retrieve-exception-history
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-resolution-is-required-for-bulk-resolve:
                  $ref: "#/components/examples/400-resolution-is-required-for-bulk-resolve"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0501-exception-not-found:
                  $ref: "#/components/examples/mtch-0501-exception-not-found"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0503-exception-cannot-transition-in-current-state:
                  $ref: "#/components/examples/mtch-0503-exception-cannot-transition-in-current-state"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Resolve an exception
      tags:
        - Exception
      x-mint:
        href: /pt/reference/products/matcher/resolve-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)
          explode: false
          in: query
          name: status
          schema:
            description: Filter by status (QUEUED, RUNNING, SUCCEEDED, FAILED, EXPIRED, CANCELED)
            type: string
        - description: Cursor for pagination (opaque)
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: Maximum number of jobs to return (default 20, max 100)
          explode: false
          in: query
          name: limit
          schema:
            default: 20
            description: Maximum number of records to return
            format: int64
            maximum: 200
            minimum: 1
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List export jobs
      tags:
        - Export Jobs
      x-mint:
        href: /pt/reference/products/matcher/list-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:
            description: Export Job ID
            format: uuid
            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"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-export-job-not-found:
                  $ref: "#/components/examples/mtch-0005-export-job-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get export job status
      tags:
        - Export Jobs
      x-mint:
        href: /pt/reference/products/matcher/retrieve-export-job
  /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:
            description: Export Job ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      responses:
        "200":
          description: |-
            Indicates that the request was successful and the response contains the expected data.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportJobResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-export-job-not-found:
                  $ref: "#/components/examples/mtch-0005-export-job-not-found"
        "409":
          description: The job is already in a terminal state.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0007-job-is-already-in-a-terminal-state:
                  $ref: "#/components/examples/mtch-0007-job-is-already-in-a-terminal-state"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Cancel an export job
      tags:
        - Export Jobs
      x-mint:
        href: /pt/reference/products/matcher/cancel-export-job
  /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:
            description: Export Job ID
            format: uuid
            type: string
      responses:
        "200":
          description: Export download details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DownloadExportJobResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-export-job-not-found:
                  $ref: "#/components/examples/mtch-0005-export-job-not-found"
        "409":
          description: Job not ready for download
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0007-export-job-is-not-ready-for-download:
                  $ref: "#/components/examples/mtch-0007-export-job-is-not-ready-for-download"
        "410":
          description: The export file has expired.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                410-export-file-has-expired:
                  $ref: "#/components/examples/410-export-file-has-expired"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0019-internal-error:
                  $ref: "#/components/examples/mtch-0019-internal-error"
      security:
        - BearerAuth: []
      summary: Download export file
      tags:
        - Export Jobs
      x-mint:
        href: /pt/reference/products/matcher/download-export-job
  /v1/fee-rules/{feeRuleId}:
    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:
            description: Fee Rule ID
            format: uuid
            type: string
      responses:
        "204":
          description: Fee rule successfully deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Fee rule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0114-fee-rule-not-found:
                  $ref: "#/components/examples/mtch-0114-fee-rule-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete a fee rule
      tags:
        - Configuration Fee Rules
      x-mint:
        href: /pt/reference/products/matcher/delete-fee-rule
    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:
            description: Fee Rule ID
            format: uuid
            type: string
      responses:
        "200":
          description: Successfully retrieved fee rule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeeRuleResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Fee rule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0114-fee-rule-not-found:
                  $ref: "#/components/examples/mtch-0114-fee-rule-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a fee rule
      tags:
        - Configuration Fee Rules
      x-mint:
        href: /pt/reference/products/matcher/retrieve-fee-rule
    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:
            description: Fee Rule ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateFeeRuleRequest"
        description: Fee rule updates
        required: true
      responses:
        "200":
          description: |-
            Successfully updated fee rule.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeeRuleResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0001-update-fee-rule-fee-rule-name-fee-rule-name-is-required:
                  $ref: "#/components/examples/mtch-0001-update-fee-rule-fee-rule-name-fee-rule-name-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Fee rule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0114-fee-rule-not-found:
                  $ref: "#/components/examples/mtch-0114-fee-rule-not-found"
        "409":
          description: Conflict — duplicate priority or name
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0107-a-fee-rule-with-this-priority-already-exists-in-the-context:
                  $ref: "#/components/examples/mtch-0107-a-fee-rule-with-this-priority-already-exists-in-the-context"
                mtch-0101-a-fee-rule-with-this-name-already-exists-in-the-context:
                  $ref: "#/components/examples/mtch-0101-a-fee-rule-with-this-name-already-exists-in-the-context"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Update a fee rule
      tags:
        - Configuration Fee Rules
      x-mint:
        href: /pt/reference/products/matcher/update-fee-rule
  /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.
          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":
          description: List of fee schedules with cursor pagination
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListFeeSchedulesResponse"
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List fee schedules
      tags:
        - Configuration Fee Schedules
      x-mint:
        href: /pt/reference/products/matcher/list-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/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFeeScheduleRequest"
        description: Fee schedule creation payload
        required: true
      responses:
        "201":
          description: |-
            Successfully created fee schedule.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeeScheduleResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-fee-schedule-items:
                  $ref: "#/components/examples/400-invalid-fee-schedule-items"
                mtch-0001-create-fee-schedule-fee-schedule-name-fee-schedule-name-is-r:
                  $ref: "#/components/examples/mtch-0001-create-fee-schedule-fee-schedule-name-fee-schedule-name-is-r"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create a fee schedule
      tags:
        - Configuration Fee Schedules
      x-mint:
        href: /pt/reference/products/matcher/create-fee-schedule
  /v1/fee-schedules/{scheduleId}:
    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:
            description: Schedule ID
            format: uuid
            type: string
      responses:
        "204":
          description: Fee schedule successfully deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Fee schedule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0115-fee-schedule-not-found:
                  $ref: "#/components/examples/mtch-0115-fee-schedule-not-found--delete-v1-fee-schedules-scheduleid"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0108-fee-schedule-is-referenced-by-fee-rules:
                  $ref: "#/components/examples/mtch-0108-fee-schedule-is-referenced-by-fee-rules"
                mtch-0108-fee-schedule-is-still-in-use:
                  $ref: "#/components/examples/mtch-0108-fee-schedule-is-still-in-use"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete a fee schedule
      tags:
        - Configuration Fee Schedules
      x-mint:
        href: /pt/reference/products/matcher/delete-fee-schedule
    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:
            description: Schedule ID
            format: uuid
            type: string
      responses:
        "200":
          description: Successfully retrieved fee schedule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeeScheduleResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Fee schedule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0115-fee-schedule-not-found:
                  $ref: "#/components/examples/mtch-0115-fee-schedule-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a fee schedule
      tags:
        - Configuration Fee Schedules
      x-mint:
        href: /pt/reference/products/matcher/retrieve-fee-schedule
    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:
            description: Schedule ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateFeeScheduleRequest"
        description: Fee schedule updates
        required: true
      responses:
        "200":
          description: |-
            Successfully updated fee schedule.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeeScheduleResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0001-fee-schedule-name-is-required:
                  $ref: "#/components/examples/mtch-0001-fee-schedule-name-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Fee schedule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0115-fee-schedule-not-found:
                  $ref: "#/components/examples/mtch-0115-fee-schedule-not-found--patch-v1-fee-schedules-scheduleid"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Update a fee schedule
      tags:
        - Configuration Fee Schedules
      x-mint:
        href: /pt/reference/products/matcher/update-fee-schedule
  /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:
            description: Schedule ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SimulateFeeRequest"
        description: Fee simulation payload
        required: true
      responses:
        "200":
          description: |-
            Fee simulation result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimulateFeeResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-gross-amount:
                  $ref: "#/components/examples/400-invalid-gross-amount"
                mtch-0001-gross-currency-invalid-currency:
                  $ref: "#/components/examples/mtch-0001-gross-currency-invalid-currency"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Fee schedule not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0115-fee-schedule-not-found:
                  $ref: "#/components/examples/mtch-0115-fee-schedule-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Simulate fee calculation
      tags:
        - Configuration Fee Schedules
      x-mint:
        href: /pt/reference/products/matcher/simulate-fee-schedule
  /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:
            description: Field map ID
            format: uuid
            type: string
      responses:
        "204":
          description: Field map successfully deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Field map not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0112-field-map-not-found:
                  $ref: "#/components/examples/mtch-0112-field-map-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete a field map
      tags:
        - Configuration Field Maps
      x-mint:
        href: /pt/reference/products/matcher/delete-field-map
    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:
            description: Field map ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateFieldMapRequest"
        description: Field map updates
        required: true
      responses:
        "200":
          description: |-
            Successfully updated field map.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldMapResponse"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0001-mapping-is-required:
                  $ref: "#/components/examples/mtch-0001-mapping-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Field map not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0112-field-map-not-found:
                  $ref: "#/components/examples/mtch-0112-field-map-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Update a field map
      tags:
        - Configuration Field Maps
      x-mint:
        href: /pt/reference/products/matcher/update-field-map
  /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. Pagination is forward-only: use the nextCursor value to fetch the next page.'
      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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List actor mappings
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/list-actor-mappings
  /v1/governance/actor-mappings/{actorId}:
    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:
            description: Actor ID
            type: string
      responses:
        "204":
          description: Actor mapping successfully deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Actor mapping not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-actor-mapping-not-found:
                  $ref: "#/components/examples/mtch-0005-actor-mapping-not-found--delete-v1-governance-actor-mappings-actorid"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete an actor mapping
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/delete-actor-mapping
    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:
            description: Actor ID
            type: string
      responses:
        "200":
          description: Successfully retrieved actor mapping
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActorMappingResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Actor mapping not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-actor-mapping-not-found:
                  $ref: "#/components/examples/mtch-0005-actor-mapping-not-found"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get an actor mapping
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/get-actor-mapping
    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:
            description: Actor ID
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpsertActorMappingRequest"
        description: Actor mapping payload
        required: true
      responses:
        "200":
          description: |-
            Actor mapping created or updated.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-at-least-one-of-displayname-or-email-must-be-provided:
                  $ref: "#/components/examples/400-at-least-one-of-displayname-or-email-must-be-provided"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Upsert an actor mapping
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/upsert-actor-mapping
  /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:
            description: Actor ID
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      responses:
        "204":
          description: |-
            Actor successfully pseudonymized.
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Actor mapping not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-actor-mapping-not-found:
                  $ref: "#/components/examples/mtch-0005-actor-mapping-not-found--post-v1-governance-actor-mappings-actorid-pseudonymize"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Pseudonymize an actor
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/pseudonymize-actor
  /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: Start date filter (YYYY-MM-DD or RFC 3339 format)
          explode: false
          in: query
          name: from
          schema:
            description: Filter archives from this date (YYYY-MM-DD or RFC3339)
            type: string
        - description: End date filter (YYYY-MM-DD or RFC 3339 format)
          explode: false
          in: query
          name: to
          schema:
            description: Filter archives until this date (YYYY-MM-DD or RFC3339)
            type: string
        - description: The maximum number of items to include in the response.
          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: The number of items to skip before returning results.
          explode: false
          in: query
          name: offset
          schema:
            default: 0
            description: Number of records to skip
            format: int64
            minimum: 0
            type: integer
      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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-from-must-be-a-valid-date-yyyy-mm-dd-or-rfc3339:
                  $ref: "#/components/examples/400-from-must-be-a-valid-date-yyyy-mm-dd-or-rfc3339"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List audit log archives
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/list-archives
  /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:
            description: Archive ID
            format: uuid
            type: string
      responses:
        "200":
          description: Archive download details with pre-signed URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArchiveDownloadResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Archive not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-archive-not-found:
                  $ref: "#/components/examples/mtch-0005-archive-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Download an audit log archive
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/download-archive
  /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
          explode: false
          in: query
          name: actor
          schema:
            description: Filter by actor ID
            type: string
        - description: Filter logs from this date (YYYY-MM-DD or RFC3339)
          explode: false
          in: query
          name: date_from
          schema:
            description: Filter logs from this date (YYYY-MM-DD or RFC3339)
            type: string
        - description: Filter logs until this date (YYYY-MM-DD or RFC3339)
          explode: false
          in: query
          name: date_to
          schema:
            description: Filter logs until this date (YYYY-MM-DD or RFC3339)
            type: string
        - description: Filter by action type
          explode: false
          in: query
          name: action
          schema:
            description: Filter by action type
            examples:
              - CREATE
            type: string
        - description: Filter by entity type
          explode: false
          in: query
          name: entity_type
          schema:
            description: Filter by entity type
            examples:
              - context
            type: string
        - description: The maximum number of items to include in the response.
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-actor-filter:
                  $ref: "#/components/examples/400-invalid-actor-filter"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List audit logs
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/list-audit-logs
  /v1/governance/audit-logs/verify:
    get:
      description: 'Re-verifies the calling tenant''s 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. Use the optional fromSeq query parameter to start the check at that tenant_seq. When the first record the check reads is not sequence 1, the check trusts that record''s stored link. It does not verify the records before it. The verdict always echoes the effective fromSeq.'
      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
        - description: "Verification floor: the first record inspected is the one with this tenant_seq. Omit to start at the chain start (seq 1)."
          explode: false
          in: query
          name: fromSeq
          schema:
            description: "Verification floor: the first record inspected is the one with this tenant_seq. Omit to start at the chain start (seq 1)."
            format: int64
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditChainVerificationResponse"
          description: OK
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Verify audit log chain integrity
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/verify-audit-log-chain
  /v1/governance/audit-logs/{id}:
    get:
      description: Use this endpoint to retrieve the details of a specific audit log entry by its identifier.
      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:
            description: Audit Log ID
            format: uuid
            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/AuditLogResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-audit-log-not-found:
                  $ref: "#/components/examples/mtch-0005-audit-log-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get audit log by ID
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/retrieve-audit-log
  /v1/governance/entities/{entityType}/{entityId}/audit-logs:
    get:
      description: Use this endpoint to retrieve the audit log entries for a specific entity. The results are ordered by creation time descending.
      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
          in: path
          name: entityType
          required: true
          schema:
            description: Entity type
            examples:
              - context
            type: string
        - description: Entity ID
          in: path
          name: entityId
          required: true
          schema:
            description: Entity ID
            format: uuid
            type: string
        - description: The maximum number of items to include in the response.
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List audit logs by entity
      tags:
        - Governance
      x-mint:
        href: /pt/reference/products/matcher/list-audit-logs-by-entity
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List AI extraction reviews (the human-review queue)
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/list-extraction-reviews
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-extraction-review-not-found:
                  $ref: "#/components/examples/mtch-0005-extraction-review-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get a single AI extraction review
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/get-extraction-review
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-extraction-review-not-found:
                  $ref: "#/components/examples/mtch-0005-extraction-review-not-found--post-v1-imports-contexts-contextid-extraction-reviews-reviewid-approve"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0324-invalid-extraction-review-status-transition-cannot-approve-f:
                  $ref: "#/components/examples/mtch-0324-invalid-extraction-review-status-transition-cannot-approve-f"
                mtch-0324-persist-approved-review-update-extraction-review-extraction:
                  $ref: "#/components/examples/mtch-0324-persist-approved-review-update-extraction-review-extraction"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Approve an AI extraction review (ingest the candidates)
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/approve-extraction-review
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-validation-failed:
                  $ref: "#/components/examples/400-validation-failed"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-extraction-review-not-found:
                  $ref: "#/components/examples/mtch-0005-extraction-review-not-found--post-v1-imports-contexts-contextid-extraction-reviews-reviewid-reject"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0324-invalid-extraction-review-status-transition-cannot-reject-fr:
                  $ref: "#/components/examples/mtch-0324-invalid-extraction-review-status-transition-cannot-reject-fr"
                mtch-0324-persist-rejected-review-update-extraction-review-extraction:
                  $ref: "#/components/examples/mtch-0324-persist-rejected-review-update-extraction-review-extraction"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Reject an AI extraction review (discard the candidates)
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/reject-extraction-review
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The maximum number of items to include in the response.
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor
            type: string
        - description: The order used to sort the results.
          explode: false
          in: query
          name: sort_order
          schema:
            description: Sort order
            enum:
              - asc
              - desc
            type: string
        - description: The field used to sort the results.
          explode: false
          in: query
          name: sort_by
          schema:
            description: Sort field
            enum:
              - id
              - created_at
              - started_at
              - completed_at
              - status
            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/ListJobsResponse"
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List ingestion jobs for a context
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/list-ingestion-jobs
  /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:
            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":
          description: Indicates that the request was successful and the response contains the expected data.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0306-job-not-found:
                  $ref: "#/components/examples/mtch-0306-job-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get ingestion job status
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/retrieve-ingestion-job
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0306-job-not-found:
                  $ref: "#/components/examples/mtch-0306-job-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List per-row import errors for a job
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/list-ingestion-job-errors
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: Job ID
          in: path
          name: jobId
          required: true
          schema:
            description: Job ID
            format: uuid
            type: string
        - description: The maximum number of items to include in the response.
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor
            type: string
        - description: The order used to sort the results.
          explode: false
          in: query
          name: sort_order
          schema:
            description: Sort order
            enum:
              - asc
              - desc
            type: string
        - description: The field used to sort the results.
          explode: false
          in: query
          name: sort_by
          schema:
            description: Sort field
            enum:
              - id
              - created_at
              - date
              - status
              - extraction_status
            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/ListTransactionsResponse"
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0306-job-not-found:
                  $ref: "#/components/examples/mtch-0306-job-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List transactions for a job
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/list-job-transactions
  /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 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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-validation-failed:
                  $ref: "#/components/examples/400-validation-failed--post-v1-imports-contexts-contextid-sources-sourceid-extract-document"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active, or document extraction is not enabled.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
                mtch-0319-document-extraction-is-not-enabled-for-this-tenant:
                  $ref: "#/components/examples/mtch-0319-document-extraction-is-not-enabled-for-this-tenant"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0321-no-transaction-candidates-could-be-extracted-from-the-docume:
                  $ref: "#/components/examples/mtch-0321-no-transaction-candidates-could-be-extracted-from-the-docume"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0318-internal-error:
                  $ref: "#/components/examples/mtch-0318-internal-error"
                mtch-0320-internal-error:
                  $ref: "#/components/examples/mtch-0320-internal-error"
      security:
        - BearerAuth: []
      summary: Enqueue a document for AI extraction (human-review required)
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/extract-document
  /v1/imports/contexts/{contextId}/sources/{sourceId}/fetch:
    post:
      description: Lists every object matching the supplied transport coordinates 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. 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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-validation-failed:
                  $ref: "#/components/examples/400-validation-failed"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0314-internal-error:
                  $ref: "#/components/examples/mtch-0314-internal-error"
      security:
        - BearerAuth: []
      summary: Trigger a manual fetch-and-ingest from an external transport
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/fetch-trigger
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-validation-failed:
                  $ref: "#/components/examples/400-validation-failed"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0315-internal-error:
                  $ref: "#/components/examples/mtch-0315-internal-error"
                mtch-0316-internal-error:
                  $ref: "#/components/examples/mtch-0316-internal-error"
      security:
        - BearerAuth: []
      summary: Propose a config-only field-map/dialect mapping for a source sample
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/propose-mapping
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
        - description: Maximum sample rows to return (default 5, max 20)
          explode: false
          in: query
          name: max_rows
          schema:
            description: Maximum sample rows to return (default 5, max 20)
            format: int64
            maximum: 20
            minimum: 1
            type: integer
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          multipart/form-data:
            schema:
              contentMediaType: application/octet-stream
              format: binary
              properties:
                file:
                  contentMediaType: application/octet-stream
                  description: Sample file to preview (CSV, JSON, XML, or ISO 20022 camt.053)
                  format: binary
                  type: string
                format:
                  description: File format (auto-detected from extension if omitted)
                  enum:
                    - csv
                    - json
                    - xml
                    - camt053
                  type: string
                max_rows:
                  description: Maximum sample rows to return (default 5, max 20)
                  type: integer
              required:
                - file
              type: object
        required: true
      responses:
        "200":
          description: |-
            File preview with detected columns and sample rows.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-file-is-required:
                  $ref: "#/components/examples/400-file-is-required--post-v1-imports-contexts-contextid-sources-sourceid-preview"
                mtch-0307-preview-file-document-parsed-but-no-elements-matched-the-exp:
                  $ref: "#/components/examples/mtch-0307-preview-file-document-parsed-but-no-elements-matched-the-exp"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: Context or source not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Preview a transaction file
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/preview-upload
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the reconciliation source.
          in: path
          name: sourceId
          required: true
          schema:
            description: Source ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          multipart/form-data:
            schema:
              contentMediaType: application/octet-stream
              format: binary
              properties:
                file:
                  contentMediaType: application/octet-stream
                  description: Transaction file (CSV, JSON, XML, or camt.053)
                  format: binary
                  type: string
                format:
                  description: Canonical file-format key. Legacy flat keys (csv, json, xml, camt053) and namespaced keys (e.g. xx/delimited/generic, br/acquirer_csv/mercadopago) are accepted; discover the full set via GET /v1/imports/formats. Send before the file part. When omitted, inferred from the .csv/.json file extension.
                  type: string
              required:
                - file
              type: object
        required: true
      responses:
        "202":
          description: |-
            Indicates that the request was accepted for processing.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-file-is-required:
                  $ref: "#/components/examples/400-file-is-required"
                mtch-0303-format-field-is-required-for-xml-uploads-and-must-precede-th:
                  $ref: "#/components/examples/mtch-0303-format-field-is-required-for-xml-uploads-and-must-precede-th"
                mtch-0304-file-is-empty:
                  $ref: "#/components/examples/mtch-0304-file-is-empty"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0301-source-not-found:
                  $ref: "#/components/examples/mtch-0301-source-not-found"
                mtch-0302-field-mapping-not-found-for-source:
                  $ref: "#/components/examples/mtch-0302-field-mapping-not-found-for-source"
        "408":
          description: The upload stalled before the file arrived.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0311-upload-stalled-no-bytes-received-for-1m0s-the-import-was-fai:
                  $ref: "#/components/examples/mtch-0311-upload-stalled-no-bytes-received-for-1m0s-the-import-was-fai"
        "413":
          description: The uploaded file exceeds the maximum allowed size.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0010-upload-exceeds-the-configured-limit-of-1073741824-bytes-inge:
                  $ref: "#/components/examples/mtch-0010-upload-exceeds-the-configured-limit-of-1073741824-bytes-inge"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0309-error-rate-policy-exceeded-200-of-1000-rows-failed-exceeding:
                  $ref: "#/components/examples/mtch-0309-error-rate-policy-exceeded-200-of-1000-rows-failed-exceeding"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Upload transaction file
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/upload-transaction-file
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: Free-text search query
          explode: false
          in: query
          name: q
          schema:
            description: Free text search across external ID and description
            type: string
        - description: Minimum transaction amount
          explode: false
          in: query
          name: amount_min
          schema:
            description: Minimum transaction amount
            type: string
        - description: Maximum transaction amount
          explode: false
          in: query
          name: amount_max
          schema:
            description: Maximum transaction amount
            type: string
        - description: Start date filter (RFC 3339 format)
          explode: false
          in: query
          name: date_from
          schema:
            description: Start date filter (RFC3339)
            format: date-time
            type: string
        - description: End date filter (RFC 3339 format)
          explode: false
          in: query
          name: date_to
          schema:
            description: End date filter (RFC3339)
            format: date-time
            type: string
        - description: Transaction reference (exact match)
          explode: false
          in: query
          name: reference
          schema:
            description: Exact external ID match
            type: string
        - description: Currency code filter
          explode: false
          in: query
          name: currency
          schema:
            description: Currency code filter
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter (UUID)
            type: string
        - description: Transaction status filter
          explode: false
          in: query
          name: status
          schema:
            description: Transaction status filter
            enum:
              - UNMATCHED
              - MATCHED
              - IGNORED
              - PENDING_REVIEW
            type: string
        - description: The maximum number of items to include in the response.
          explode: false
          in: query
          name: limit
          schema:
            default: 20
            description: Maximum number of records to return
            format: int64
            maximum: 50
            minimum: 1
            type: integer
        - description: The number of items to skip before returning results.
          explode: false
          in: query
          name: offset
          schema:
            default: 0
            description: Number of records to skip
            format: int64
            minimum: 0
            type: integer
      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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-search-parameters:
                  $ref: "#/components/examples/400-invalid-search-parameters"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Search transactions
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/search-transactions
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The unique identifier of the transaction.
          in: path
          name: transactionId
          required: true
          schema:
            description: Transaction ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-reason-is-required:
                  $ref: "#/components/examples/400-reason-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-transaction-not-found:
                  $ref: "#/components/examples/mtch-0005-transaction-not-found"
        "409":
          description: Only an unmatched transaction can be ignored.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0305-transaction-cannot-be-ignored-only-unmatched-transactions-ca:
                  $ref: "#/components/examples/mtch-0305-transaction-cannot-be-ignored-only-unmatched-transactions-ca"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Ignore a transaction
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/ignore-transaction
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Browse the supported format catalog
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/browse-format-catalog
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List operator fixed-width layout templates
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/list-layout-templates
    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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-layout-template:
                  $ref: "#/components/examples/400-invalid-layout-template"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0007-layout-template-already-exists-for-this-format:
                  $ref: "#/components/examples/mtch-0007-layout-template-already-exists-for-this-format"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0006-layout-template-validation-catalog-field-overruns-record-wid:
                  $ref: "#/components/examples/mtch-0006-layout-template-validation-catalog-field-overruns-record-wid"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Submit an operator fixed-width layout template
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/submit-layout-template
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-layout-template-not-found:
                  $ref: "#/components/examples/mtch-0005-layout-template-not-found--delete-v1-imports-formats-templates-templateid"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Delete an operator fixed-width layout template
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/delete-layout-template
    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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-layout-template-not-found:
                  $ref: "#/components/examples/mtch-0005-layout-template-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get an operator fixed-width layout template
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/get-layout-template
    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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-layout-template:
                  $ref: "#/components/examples/400-invalid-layout-template--put-v1-imports-formats-templates-templateid"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-layout-template-not-found:
                  $ref: "#/components/examples/mtch-0005-layout-template-not-found--put-v1-imports-formats-templates-templateid"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0007-layout-template-already-exists-for-this-format:
                  $ref: "#/components/examples/mtch-0007-layout-template-already-exists-for-this-format--put-v1-imports-formats-templates-templateid"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0006-layout-template-validation-catalog-field-overruns-record-wid:
                  $ref: "#/components/examples/mtch-0006-layout-template-validation-catalog-field-overruns-record-wid--put-v1-imports-formats-templates-templateid"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Replace an operator fixed-width layout template
      tags:
        - Ingestion
      x-mint:
        href: /pt/reference/products/matcher/update-layout-template
  /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
          explode: false
          in: query
          name: contextId
          required: true
          schema:
            description: Context ID the adjustment belongs to
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAdjustmentRequest"
        description: Adjustment payload
        required: true
      responses:
        "201":
          description: |-
            Indicates that the resource was successfully created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdjustmentEnvelope"
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-amount-format:
                  $ref: "#/components/examples/400-invalid-amount-format"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-transaction-not-found:
                  $ref: "#/components/examples/mtch-0005-transaction-not-found--post-v1-matching-adjustments"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Create an adjustment
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/create-adjustment
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-transaction-id-is-required:
                  $ref: "#/components/examples/400-transaction-id-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-target-transaction-not-found-in-context:
                  $ref: "#/components/examples/mtch-0005-target-transaction-not-found-in-context"
                mtch-0005-reconciliation-context-not-found:
                  $ref: "#/components/examples/mtch-0005-reconciliation-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List match candidates for a transaction
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/list-match-candidates
  /v1/matching/contexts/{contextId}/adjustments:
    get:
      description: Use this endpoint to list the balancing entries recorded against a context, newest first. Use `matchGroupId` to narrow the list to one match group.
      operationId: listAdjustments
      parameters:
        - description: Context ID whose adjustments to list
          in: path
          name: contextId
          required: true
          schema:
            description: Context ID whose adjustments to list
            format: uuid
            type: string
        - description: Narrow to the entries balancing one match group. Omit to read the whole context.
          explode: false
          in: query
          name: matchGroupId
          schema:
            description: Narrow to the entries balancing one match group. Omit to read the whole context.
            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: Opaque pagination cursor
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor
            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/ListAdjustmentsResponse"
          description: OK
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters--get-v1-matching-contexts-contextid-adjustments"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List recorded adjustments
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/list-recorded-adjustments
  /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
              - WITHDRAWN
            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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters--get-v1-matching-contexts-contextid-open-items"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List open items
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/list-open-items
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0410-internal-error:
                  $ref: "#/components/examples/mtch-0410-internal-error"
      security:
        - BearerAuth: []
      summary: List AI match-rule suggestions (the human-review queue)
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/list-match-rule-suggestions
    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. 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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active, or rule suggestion is not enabled.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
                mtch-0409-rule-suggestion-is-not-enabled-for-this-tenant:
                  $ref: "#/components/examples/mtch-0409-rule-suggestion-is-not-enabled-for-this-tenant"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0410-internal-error:
                  $ref: "#/components/examples/mtch-0410-internal-error"
                mtch-0411-internal-error:
                  $ref: "#/components/examples/mtch-0411-internal-error"
      security:
        - BearerAuth: []
      summary: Produce AI match-rule suggestions (human-review required)
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/suggest-match-rules
  /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
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-rule-suggestion-not-found:
                  $ref: "#/components/examples/mtch-0005-rule-suggestion-not-found"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0413-approving-rule-suggestion-invalid-rule-suggestion-review-sta:
                  $ref: "#/components/examples/mtch-0413-approving-rule-suggestion-invalid-rule-suggestion-review-sta"
                mtch-0413-persisting-approved-review-update-rule-suggestion-review-rul:
                  $ref: "#/components/examples/mtch-0413-persisting-approved-review-update-rule-suggestion-review-rul"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0412-the-approved-suggestion-failed-validation:
                  $ref: "#/components/examples/mtch-0412-the-approved-suggestion-failed-validation"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0410-internal-error:
                  $ref: "#/components/examples/mtch-0410-internal-error"
      security:
        - BearerAuth: []
      summary: Approve an AI match-rule suggestion (create the rule)
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/approve-match-rule-suggestion
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-validation-failed:
                  $ref: "#/components/examples/400-validation-failed"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-rule-suggestion-not-found:
                  $ref: "#/components/examples/mtch-0005-rule-suggestion-not-found"
        "409":
          description: The request conflicts with the current state of the resource.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0413-rejecting-rule-suggestion-invalid-rule-suggestion-review-sta:
                  $ref: "#/components/examples/mtch-0413-rejecting-rule-suggestion-invalid-rule-suggestion-review-sta"
                mtch-0413-persisting-rejected-review-update-rule-suggestion-review-rul:
                  $ref: "#/components/examples/mtch-0413-persisting-rejected-review-update-rule-suggestion-review-rul"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0410-internal-error:
                  $ref: "#/components/examples/mtch-0410-internal-error"
      security:
        - BearerAuth: []
      summary: Reject an AI match-rule suggestion (discard it)
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/reject-match-rule-suggestion
  /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:
            description: Reconciliation context ID
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0401-no-sources-configured-for-context:
                  $ref: "#/components/examples/mtch-0401-no-sources-configured-for-context"
                mtch-0402-at-least-two-sources-are-required:
                  $ref: "#/components/examples/mtch-0402-at-least-two-sources-are-required"
                mtch-0404-1-1-contexts-require-exactly-one-source-per-side:
                  $ref: "#/components/examples/mtch-0404-1-1-contexts-require-exactly-one-source-per-side"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "409":
          description: Another match run is already in progress for this context.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0408-another-match-run-is-already-in-progress-for-this-context:
                  $ref: "#/components/examples/mtch-0408-another-match-run-is-already-in-progress-for-this-context"
        "422":
          description: The request was well-formed but contains semantic errors.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0406-fee-normalization-is-enabled-but-no-fee-rules-are-configured:
                  $ref: "#/components/examples/mtch-0406-fee-normalization-is-enabled-but-no-fee-rules-are-configured"
                mtch-0407-fee-rules-are-misconfigured-for-this-context:
                  $ref: "#/components/examples/mtch-0407-fee-rules-are-misconfigured-for-this-context"
                422-validation-failed:
                  $ref: "#/components/examples/422-validation-failed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: The service is temporarily unavailable. Please try again later.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0008-internal-error:
                  $ref: "#/components/examples/mtch-0008-internal-error"
      security:
        - BearerAuth: []
      summary: Trigger a matching run
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/run-match
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: The maximum number of items to include in the response.
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor
            type: string
        - description: The order used to sort the results.
          explode: false
          in: query
          name: sort_order
          schema:
            description: Sort order
            enum:
              - asc
              - desc
            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/ListMatchRunsResponse"
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters--get-v1-matching-contexts-contextid-runs"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List match runs
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/list-match-runs
  /v1/matching/groups/{matchGroupId}:
    delete:
      description: Use this endpoint to break an incorrect match group. Send the reason in the request. The transactions of the group return 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:
            description: Match Group ID
            format: uuid
            type: string
        - description: Context ID
          explode: false
          in: query
          name: contextId
          required: true
          schema:
            description: Context ID the group belongs to
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-reason-is-required:
                  $ref: "#/components/examples/400-reason-is-required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-match-group-not-found:
                  $ref: "#/components/examples/mtch-0005-match-group-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        '409':
          description: This un-match was not applied.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
      security:
        - BearerAuth: []
      summary: Break/Unmatch a match group
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/unmatch-group
  /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
          explode: false
          in: query
          name: contextId
          required: true
          schema:
            description: Context ID the transactions belong to
            format: uuid
            type: string
        - $ref: "#/components/parameters/XIdempotency"
      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.
          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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-duplicate-transaction-ids-provided:
                  $ref: "#/components/examples/400-duplicate-transaction-ids-provided"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-one-or-more-transactions-not-found:
                  $ref: "#/components/examples/mtch-0005-one-or-more-transactions-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        '409':
          description: One or more of these transactions were matched by another request while this one ran; no match was created. Refresh the transactions and try again.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Detail'
      security:
        - BearerAuth: []
      summary: Create a manual match
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/create-manual-match
  /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:
            description: Run ID
            format: uuid
            type: string
        - description: "Context ID"
          explode: false
          in: query
          name: contextId
          schema:
            description: "Context ID the run belongs to. Optional: when omitted the run is resolved by id within the tenant."
            format: uuid
            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"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                mtch-0005-match-run-not-found:
                  $ref: "#/components/examples/mtch-0005-match-run-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get match run
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/retrieve-match-run
  /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:
            description: Run ID
            format: uuid
            type: string
        - description: Context ID
          explode: false
          in: query
          name: contextId
          required: true
          schema:
            description: Context ID the run belongs to
            format: uuid
            type: string
        - description: The maximum number of items to include in the response.
          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: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor
            type: string
        - description: The order used to sort the results.
          explode: false
          in: query
          name: sort_order
          schema:
            description: Sort order
            enum:
              - asc
              - desc
            type: string
        - description: The field used to sort the results.
          explode: false
          in: query
          name: sort_by
          schema:
            description: Sort field
            enum:
              - id
              - created_at
              - status
            type: string
        - description: Filter by match-group lifecycle status. Applied server-side so the filter is honest across all pages, not just the loaded one.
          explode: false
          in: query
          name: status
          schema:
            description: Filter by match-group lifecycle status. Applied server-side so the filter is honest across all pages, not just the loaded one.
            enum:
              - PROPOSED
              - CONFIRMED
              - REJECTED
              - REVOKED
            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/ListMatchGroupsResponse"
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-pagination-parameters:
                  $ref: "#/components/examples/400-invalid-pagination-parameters--get-v1-matching-runs-runid-groups"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get match run results
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/list-match-run-groups
  /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
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-specify-either-a-rule-id-or-an-inline-rule-definition-not-bo:
                  $ref: "#/components/examples/400-specify-either-a-rule-id-or-an-inline-rule-definition-not-bo"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
                404-match-rule-not-found-in-context:
                  $ref: "#/components/examples/404-match-rule-not-found-in-context"
                404-reconciliation-context-not-found:
                  $ref: "#/components/examples/404-reconciliation-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Simulate a match rule against a context (read-only dry run)
      tags:
        - Matching
      x-mint:
        href: /pt/reference/products/matcher/simulate-match-rule
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get all dashboard aggregates
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/get-dashboard-aggregates
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get cash impact summary
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/get-cash-impact
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get match rate statistics
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/get-match-rate-stats
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get comprehensive dashboard metrics
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/get-dashboard-metrics
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get SLA statistics
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/get-sla-stats
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get source breakdown
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/get-source-breakdown
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get volume statistics
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/get-volume-stats
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Count exceptions
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/count-exceptions
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            type: string
        - description: Export format (csv or pdf)
          explode: false
          in: query
          name: format
          schema:
            default: csv
            description: Export format (csv or pdf)
            enum:
              - csv
              - pdf
            type: string
      responses:
        "200":
          description: Indicates that the request was successful and the response contains the expected data.
          content:
            application/json:
              schema:
                contentEncoding: base64
                type: string
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Export exceptions report
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/export-exceptions-report
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            type: string
        - description: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: The maximum number of items to include in the response.
          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: Sort order by date
          explode: false
          in: query
          name: sort_order
          schema:
            default: desc
            description: Sort order for created_at (asc or desc; defaults to desc)
            enum:
              - asc
              - desc
            type: string
      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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List matched transactions report
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/list-matched-report
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            type: string
        - description: Export format (csv or pdf)
          explode: false
          in: query
          name: format
          schema:
            default: csv
            description: Export format (csv or pdf)
            enum:
              - csv
              - pdf
            type: string
      responses:
        "200":
          description: Indicates that the request was successful and the response contains the expected data.
          content:
            application/json:
              schema:
                contentEncoding: base64
                type: string
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Export matched transactions report
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/export-matched-report
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Count matches
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/count-matches
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Get reconciliation summary report
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/get-summary-report
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            type: string
        - description: Export format (csv or pdf)
          explode: false
          in: query
          name: format
          schema:
            default: csv
            description: Export format (csv or pdf)
            enum:
              - csv
              - pdf
            type: string
      responses:
        "200":
          description: Indicates that the request was successful and the response contains the expected data.
          content:
            application/json:
              schema:
                contentEncoding: base64
                type: string
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Export summary report
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/export-summary-report
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Count transactions
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/count-transactions
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days unless unbounded=true."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days unless unbounded=true."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            type: string
        - description: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: The maximum number of items to include in the response.
          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: Sort order by date
          explode: false
          in: query
          name: sort_order
          schema:
            default: desc
            description: Sort order for created_at (asc or desc; defaults to desc)
            enum:
              - asc
              - desc
            type: string
        - description: When true, ignore date_from/date_to and the 90-day window cap to return the full unmatched backlog (still cursor-paged). Defaults to false (30-day default window, 90-day cap).
          explode: false
          in: query
          name: unbounded
          schema:
            default: false
            description: When true, ignore date_from/date_to and the 90-day window cap to return the full unmatched backlog (still cursor-paged). Defaults to false (30-day default window, 90-day cap).
            type: boolean
      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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List unmatched transactions report
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/list-unmatched-report
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days unless unbounded=true."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days unless unbounded=true."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            type: string
        - description: When true, ignore date_from/date_to and the 90-day window cap to count the full unmatched backlog. Defaults to false (30-day default window, 90-day cap).
          explode: false
          in: query
          name: unbounded
          schema:
            default: false
            description: When true, ignore date_from/date_to and the 90-day window cap to count the full unmatched backlog. Defaults to false (30-day default window, 90-day cap).
            type: boolean
      responses:
        "200":
          description: Unmatched count
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportCountResponse"
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Count unmatched items
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/count-unmatched
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            type: string
        - description: Export format (csv or pdf)
          explode: false
          in: query
          name: format
          schema:
            default: csv
            description: Export format (csv or pdf)
            enum:
              - csv
              - pdf
            type: string
      responses:
        "200":
          description: Indicates that the request was successful and the response contains the expected data.
          content:
            application/json:
              schema:
                contentEncoding: base64
                type: string
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Export unmatched transactions report
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/export-unmatched-report
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            type: string
        - description: The cursor value for retrieving the next page of results.
          explode: false
          in: query
          name: cursor
          schema:
            description: Cursor for pagination (opaque)
            type: string
        - description: The maximum number of items to include in the response.
          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: Sort order by date
          explode: false
          in: query
          name: sort_order
          schema:
            default: desc
            description: Sort order for created_at (asc or desc; defaults to desc)
            enum:
              - asc
              - desc
            type: string
      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/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: List variance report
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/list-variance-report
  /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:
            description: Context ID
            format: uuid
            type: string
        - description: "Start date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_from
          schema:
            description: "Start date (YYYY-MM-DD), inclusive. Optional: defaults to 30 days before date_to. Window may not exceed 90 days."
            format: date
            type: string
        - description: "End date (YYYY-MM-DD)"
          explode: false
          in: query
          name: date_to
          schema:
            description: "End date (YYYY-MM-DD), inclusive. Optional: defaults to tomorrow (UTC). Window may not exceed 90 days."
            format: date
            type: string
        - description: Source ID filter
          explode: false
          in: query
          name: source_id
          schema:
            description: Source ID filter
            format: uuid
            type: string
        - description: Export format (csv or pdf)
          explode: false
          in: query
          name: format
          schema:
            default: csv
            description: Export format (csv or pdf)
            enum:
              - csv
              - pdf
            type: string
      responses:
        "200":
          description: Indicates that the request was successful and the response contains the expected data.
          content:
            application/json:
              schema:
                contentEncoding: base64
                type: string
        "400":
          description: The request contains invalid parameters or payload.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                400-invalid-date-range:
                  $ref: "#/components/examples/400-invalid-date-range"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: You do not have permission to access this resource, or the context is not active.
          content:
            text/plain:
              schema:
                type: string
              example: Forbidden
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                TenantClaimRequired:
                  summary: Tenant claim missing
                  value:
                    type: "https://errors.lerian.studio/v1/MTCH-0004"
                    title: Forbidden
                    status: 403
                    detail: tenant claim required
                    code: MTCH-0004
                mtch-0012-context-is-not-active:
                  $ref: "#/components/examples/mtch-0012-context-is-not-active"
        "404":
          description: The requested resource was not found.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Detail"
              examples:
                mtch-0005-context-not-found:
                  $ref: "#/components/examples/mtch-0005-context-not-found"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
      security:
        - BearerAuth: []
      summary: Export variance report
      tags:
        - Reporting
      x-mint:
        href: /pt/reference/products/matcher/export-variance-report
components:
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: 'Bearer token authentication (format: "Bearer {token}")'
      scheme: bearer
      type: http
    CallbackToken:
      description: Opaque bearer token authenticating an external system's inbound exception callback.
      in: header
      name: X-Callback-Token
      type: apiKey
    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:
    XIdempotency:
      name: X-Idempotency
      in: header
      required: false
      description: |-
        Optional idempotency key for safe retries. Matcher reads the key only from this header, and only when you send one. A request that carries a key only in `X-Idempotency-Key` or `Idempotency-Key` is refused with `400` (`MTCH-0015`), and nothing is processed. If the same key is sent again and the original request was already processed, the stored response is returned with `X-Idempotency-Replayed: true`. A malformed key returns `400`, a key whose first request is still in progress returns `409`, and an idempotency storage failure returns `500`. These refusals are problem documents.
      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.
      schema:
        type: boolean
    RetryAfter:
      description: Seconds to wait before you retry.
      schema:
        type: integer
        example: 30
    XRateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
        example: 100
    XRateLimitRemaining:
      description: Requests left in the current window. Always `0` on a `429`.
      schema:
        type: integer
        example: 0
    XRateLimitReset:
      description: Unix time, in seconds, when the current window resets.
      schema:
        type: integer
        example: 1767225600
  responses:
    Unauthorized:
      description: The request lacks valid authentication credentials.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Detail"
          examples:
            MissingToken:
              summary: Missing token
              value:
                type: "https://errors.lerian.studio/v1/MTCH-0003"
                title: Unauthorized
                status: 401
                detail: missing authorization token
                code: MTCH-0003
            InvalidToken:
              summary: Invalid token
              value:
                type: "https://errors.lerian.studio/v1/MTCH-0003"
                title: Unauthorized
                status: 401
                detail: invalid authorization token
                code: MTCH-0003
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
        text/plain:
          schema:
            type: string
          example: Unauthorized
    Forbidden:
      description: You do not have permission to access this resource.
      content:
        text/plain:
          schema:
            type: string
          example: Forbidden
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Detail"
          examples:
            TenantClaimRequired:
              summary: Tenant claim missing
              value:
                type: "https://errors.lerian.studio/v1/MTCH-0004"
                title: Forbidden
                status: 403
                detail: tenant claim required
                code: MTCH-0004
    ValidationFailed:
      description: The request failed validation. The `errors` list names each value that failed.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Detail"
          example:
            title: Unprocessable Entity
            status: 422
            detail: validation failed
            errors:
              - message: expected required property name to be present
                location: body
    TooManyRequests:
      description: The request exceeded the rate limit. Wait the number of seconds in `Retry-After`, then retry.
      headers:
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
        X-RateLimit-Limit:
          $ref: "#/components/headers/XRateLimitLimit"
        X-RateLimit-Remaining:
          $ref: "#/components/headers/XRateLimitRemaining"
        X-RateLimit-Reset:
          $ref: "#/components/headers/XRateLimitReset"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RateLimitErrorResponse"
          example:
            code: 429
            title: rate_limit_exceeded
            message: rate limit exceeded
    InternalServerError:
      description: An unexpected error occurred on the server.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Detail"
          example:
            type: https://errors.lerian.studio/v1/MTCH-0002
            title: Internal Server Error
            status: 500
            detail: internal error
            code: MTCH-0002
        text/plain:
          schema:
            type: string
          example: Internal Server Error
  schemas:
    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: "Always empty: this list pages forward only. To go back, re-send a cursor you already followed, or omit it for the first page"
          type: string
      required:
        - items
        - limit
      type: object
    ActorMappingResponse:
      additionalProperties: false
      properties:
        actorId:
          description: Opaque actor identifier the PII mapping is keyed on
          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
        displayName:
          description: Human-readable display name for the actor; absent when not set or after pseudonymization
          examples:
            - John Doe
          type: string
        email:
          description: Email address of the actor; absent when not set or after pseudonymization
          examples:
            - john.doe@example.com
          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
    AddCommentRequest:
      additionalProperties: false
      properties:
        content:
          description: Comment content
          examples:
            - This transaction needs review by the finance team.
          maxLength: 5000
          minLength: 1
          type: string
      required:
        - content
      type: object
    AdjustEntryRequest:
      additionalProperties: false
      properties:
        amount:
          description: Adjustment amount as a decimal string in the field's currency; must be positive (enforced by the use case)
          examples:
            - "150.50"
          type: string
        currency:
          description: ISO 4217 currency code (3 letters) the adjustment amount is denominated in
          examples:
            - USD
          maxLength: 3
          minLength: 3
          type: string
        effectiveAt:
          description: When the adjustment takes effect, as an RFC 3339 timestamp
          examples:
            - "2025-01-20T10:30:00Z"
          format: date-time
          type: string
        notes:
          description: Additional notes explaining the adjustment
          examples:
            - Correcting processing fee discrepancy
          maxLength: 1000
          minLength: 1
          type: string
        reasonCode:
          description: Reason code for the adjustment
          examples:
            - FEE_ADJUSTMENT
          maxLength: 255
          minLength: 1
          type: string
      required:
        - reasonCode
        - notes
        - amount
        - currency
        - effectiveAt
      type: object
    AdjustmentEnvelope:
      additionalProperties: false
      properties:
        adjustment:
          $ref: "#/components/schemas/AdjustmentResponse"
          description: The balancing adjustment that was created
      required:
        - adjustment
      type: object
    AdjustmentResponse:
      additionalProperties: false
      properties:
        amount:
          description: Adjustment amount as a decimal string in the adjustment currency's minor-unit precision
          examples:
            - "10.50"
          type: string
        contextId:
          description: Reconciliation context ID this adjustment belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        createdAt:
          description: Creation timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        createdBy:
          description: Principal that created the adjustment
          examples:
            - user@example.com
          type: string
        currency:
          description: ISO 4217 currency code of the adjustment
          examples:
            - USD
          type: string
        description:
          description: Human-readable description of the adjustment
          examples:
            - Bank wire fee adjustment
          type: string
        direction:
          description: "Direction of the entry: DEBIT explains a shortfall (moves the outstanding variance up, toward zero), CREDIT explains a surplus (moves it down)"
          enum:
            - DEBIT
            - CREDIT
          examples:
            - DEBIT
          type: string
        id:
          description: Unique identifier for the adjustment
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        matchGroupId:
          description: Match group the adjustment balances; set when the adjustment targets a group
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        reason:
          description: Reason the adjustment was recorded
          examples:
            - Variance due to bank processing fee
          type: string
        transactionId:
          description: Single transaction the adjustment balances; set when the adjustment targets one transaction
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        type:
          description: "Adjustment type: BANK_FEE (bank charge), FX_DIFFERENCE (currency conversion variance), ROUNDING (minor-unit rounding), WRITE_OFF (uncollectible balance), or MISCELLANEOUS (other)"
          enum:
            - BANK_FEE
            - FX_DIFFERENCE
            - ROUNDING
            - WRITE_OFF
            - MISCELLANEOUS
          examples:
            - BANK_FEE
          type: string
        updatedAt:
          description: Last update timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - contextId
        - type
        - direction
        - amount
        - currency
        - description
        - reason
        - createdBy
        - createdAt
        - updatedAt
      type: object
    AgeBucketDTO:
      additionalProperties: false
      properties:
        bucket:
          description: Age range label for the bucket (e.g. 0-24h, 24-48h, >7d).
          examples:
            - 0-24h
          type: string
        value:
          description: Number of items falling into this age bucket.
          examples:
            - 15
          format: int64
          type: integer
      required:
        - bucket
        - value
      type: object
    AgeExposureResponse:
      additionalProperties: false
      properties:
        amount:
          description: Unreconciled monetary exposure in this age bucket, as a decimal string.
          examples:
            - "10000.00"
          type: string
        bucket:
          description: Age range label for the bucket (e.g. 0-24h, 24-48h, >7d).
          examples:
            - 0-24h
          type: string
        transactionCount:
          description: Number of unmatched transactions in this age bucket.
          examples:
            - 120
          format: int64
          type: integer
      required:
        - bucket
        - amount
        - transactionCount
      type: object
    AggregatorConnectionListItem:
      additionalProperties: false
      properties:
        accountRef:
          description: Stored opaque vendor account reference (Pluggy itemId, Belvo link id); empty while the connection is awaiting consent
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          type: string
        awaitingConsent:
          description: Whether the connection is still awaiting the end customer's vendor consent (no vendor item/link bound yet)
          examples:
            - false
          type: boolean
        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
        testable:
          description: Whether Matcher can run a connectivity test for this connection right now (its vendor has a test path AND it is bound to a vendor item/link)
          examples:
            - true
          type: boolean
        vendor:
          description: Aggregator vendor the connection is bound to
          enum:
            - pluggy
            - belvo
          examples:
            - pluggy
          type: string
      required:
        - id
        - vendor
        - configName
        - baseUrl
        - accountRef
        - testable
        - awaitingConsent
      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. Omit to create a connection awaiting consent — the connect flow binds it after the end customer authorizes.
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          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
        - clientId
        - secret
      type: object
    AggregatorConnectionResponse:
      additionalProperties: false
      properties:
        accountRef:
          description: Stored opaque vendor account reference (Pluggy itemId, Belvo link id); empty while the connection is awaiting consent
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          type: string
        awaitingConsent:
          description: Whether the connection is still awaiting the end customer's vendor consent (no vendor item/link bound yet)
          examples:
            - false
          type: boolean
        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
        - awaitingConsent
      type: object
    AggregatorConsentTokenResponse:
      additionalProperties: false
      properties:
        accountRef:
          description: Vendor item/link id this token was scoped to (the stored binding); empty on a first consent. Pass it to the vendor widget's update mode alongside the token — do not substitute a locally cached value.
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          type: string
        configName:
          description: Config name of the connection the token was minted for
          examples:
            - pluggy-main
          type: string
        expiresAt:
          description: UTC instant after which the vendor rejects this consent token
          examples:
            - "2026-08-23T12:30:00Z"
          format: date-time
          type: string
        reconsent:
          description: Whether the token re-authorizes the connection's existing vendor item/link (true) or will create a new one (false)
          examples:
            - false
          type: boolean
        token:
          description: Consent token for the vendor widget. Pass it to the widget.
          examples:
            - eyJhbGciOi...
          type: string
        vendor:
          description: Aggregator vendor the consent token was minted against
          enum:
            - pluggy
            - belvo
          examples:
            - pluggy
          type: string
      required:
        - vendor
        - configName
        - token
        - expiresAt
        - reconsent
        - 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
    ArchiveDownloadResponse:
      additionalProperties: false
      properties:
        checksum:
          description: "Hex-encoded SHA-256 of the decompressed archive content"
          type: string
        downloadUrl:
          description: Time-limited presigned URL for downloading the archive object
          examples:
            - https://s3.amazonaws.com/bucket/archive.gz?X-Amz-Signature=...
          type: string
        expiresAt:
          description: Expiration time of the download URL, in RFC 3339 format (UTC); the URL is rejected after this instant
          examples:
            - "2026-02-05T13:00:00Z"
          type: string
      required:
        - downloadUrl
        - expiresAt
        - checksum
      type: object
    ArchiveMetadataResponse:
      additionalProperties: false
      properties:
        archivedAt:
          description: Timestamp when archival completed, in RFC 3339 format (UTC); absent until the archive finishes
          examples:
            - "2024-04-01T02:30:00Z"
          type: string
        checksum:
          description: "Hex-encoded SHA-256 of the decompressed archive content; present only when persisted"
          type: string
        compressedSizeBytes:
          description: Compressed file size of the archive object, in bytes
          examples:
            - 10485760
          format: int64
          type: integer
        dateRangeEnd:
          description: End of the archived date range, in RFC 3339 format (UTC)
          examples:
            - "2024-03-31T23:59:59Z"
          type: string
        dateRangeStart:
          description: Start of the archived date range, in RFC 3339 format (UTC)
          examples:
            - "2024-01-01T00:00:00Z"
          type: string
        id:
          description: Unique identifier (UUID) for the archive
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        partitionName:
          description: Name of the database partition that was archived
          examples:
            - audit_logs_2024_q1
          type: string
        rowCount:
          description: Number of audit log rows captured in the archive
          examples:
            - 150000
          format: int64
          type: integer
        status:
          description: Archive status. Only COMPLETE archives are listed by this endpoint (in-progress and failed archives are not surfaced)
          enum:
            - COMPLETE
          examples:
            - COMPLETE
          type: string
        storageClass:
          description: Object-storage class the archive is stored under. STANDARD/STANDARD_IA/ONEZONE_IA are immediately readable tiers (IA = infrequent access); INTELLIGENT_TIERING auto-moves objects between tiers; GLACIER_IR is instant-retrieval cold storage; GLACIER and DEEP_ARCHIVE are archival tiers that require a restore before download
          enum:
            - STANDARD
            - STANDARD_IA
            - ONEZONE_IA
            - INTELLIGENT_TIERING
            - GLACIER_IR
            - GLACIER
            - DEEP_ARCHIVE
          examples:
            - GLACIER
          type: string
      required:
        - id
        - partitionName
        - dateRangeStart
        - dateRangeEnd
        - rowCount
        - compressedSizeBytes
        - storageClass
        - status
      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
        fromSeq:
          description: "Effective verification floor: the first tenant_seq eligible for inspection."
          examples:
            - 1
          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
        - fromSeq
        - verifiedCount
        - truncated
      type: object
    AuditLogResponse:
      additionalProperties: false
      properties:
        action:
          description: Action that was performed on the entity (e.g. CREATE, UPDATE, DELETE)
          examples:
            - CREATE
          type: string
        actorId:
          description: Identifier of the actor who performed the action; absent for system-originated changes
          examples:
            - user@example.com
          type: string
        changes:
          description: JSON diff of the changes made to the entity; when the diff exceeded the outbox payload cap this carries a truncation marker envelope instead of the full diff (see truncated and originalSize)
          maxItems: 10000
        createdAt:
          description: Creation timestamp in RFC 3339 format (UTC)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        entityId:
          description: Identifier (UUID) of the entity that was modified
          examples:
            - 550e8400-e29b-41d4-a716-446655440002
          type: string
        entityType:
          description: Type of entity that was modified (e.g. reconciliation_context, match_rule)
          examples:
            - reconciliation_context
          type: string
        hashVersion:
          description: Version of the canonicalization scheme used to compute recordHash
          examples:
            - 1
          format: int32
          type: integer
        id:
          description: Unique identifier (UUID) for the audit log entry
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        originalSize:
          description: Byte size of the original diff before truncation; zero when truncated is false or the marker was malformed
          examples:
            - 0
          format: int64
          type: integer
        prevHash:
          description: Lowercase-hex SHA-256 hash of the previous record; the genesis record links to 32 zero bytes
          examples:
            - "0000000000000000000000000000000000000000000000000000000000000000"
          type: string
        recordHash:
          description: "Lowercase-hex SHA-256 hash of this record: SHA-256(prevHash || canonical content); empty for pre-hash-chain records"
          examples:
            - 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
          type: string
        tenantId:
          description: Tenant ID (UUID) that owns this audit log entry
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
          type: string
        tenantSeq:
          description: 1-based monotonic position of this entry within its tenant's audit hash chain
          examples:
            - 42
          format: int64
          type: integer
        truncated:
          description: True when the original audit diff exceeded the outbox payload cap and was replaced with a truncation marker; consumers should treat changes as a metadata envelope, not the full diff, in this case
          examples:
            - false
          type: boolean
      required:
        - id
        - tenantId
        - entityType
        - entityId
        - action
        - changes
        - truncated
        - originalSize
        - createdAt
        - tenantSeq
        - recordHash
        - prevHash
        - hashVersion
      type: object
    BreakdownMetricsResponse:
      additionalProperties: false
      properties:
        agedBreaks:
          description: AGED_BREAK open-item exceptions grouped into a long-tail age scale (<7d, 7-30d, >30d).
          items:
            $ref: "#/components/schemas/AgeBucketDTO"
          maxItems: 20
          type:
            - array
            - "null"
        byAge:
          description: Exception counts grouped into age buckets.
          items:
            $ref: "#/components/schemas/AgeBucketDTO"
          maxItems: 20
          type:
            - array
            - "null"
        byReason:
          additionalProperties:
            format: int64
            type: integer
          description: Exception counts keyed by exception reason code.
          type: object
        byRule:
          description: Match counts broken down by the match rule that produced them.
          items:
            $ref: "#/components/schemas/RuleMatchCountDTO"
          maxItems: 100
          type:
            - array
            - "null"
        bySeverity:
          additionalProperties:
            format: int64
            type: integer
          description: Exception counts keyed by severity level (e.g. LOW, MEDIUM, HIGH, CRITICAL).
          type: object
      required:
        - bySeverity
        - byReason
        - byRule
        - byAge
        - agedBreaks
      type: object
    BulkActionResponse:
      additionalProperties: false
      properties:
        failed:
          description: Per-exception failures for the items that could not be processed
          items:
            $ref: "#/components/schemas/BulkFailure"
          type:
            - array
            - "null"
        succeeded:
          description: Identifiers (UUIDs) of exceptions that were processed successfully
          items:
            type: string
          type:
            - array
            - "null"
        total:
          description: Total number of exceptions attempted (succeeded plus failed)
          examples:
            - 5
          format: int64
          type: integer
      required:
        - succeeded
        - failed
        - total
      type: object
    BulkAssignRequest:
      additionalProperties: false
      properties:
        assignee:
          description: User to assign exceptions to
          examples:
            - user@example.com
          maxLength: 255
          minLength: 1
          type: string
        exceptionIds:
          description: Exception IDs to assign
          items:
            format: uuid
            type: string
          maxItems: 100
          minItems: 1
          type:
            - array
            - "null"
      required:
        - exceptionIds
        - assignee
      type: object
    BulkDispatchRequest:
      additionalProperties: false
      properties:
        exceptionIds:
          description: Exception IDs to dispatch
          items:
            format: uuid
            type: string
          maxItems: 100
          minItems: 1
          type:
            - array
            - "null"
        queue:
          description: Optional queue or team assignment
          examples:
            - RECON-TEAM
          maxLength: 255
          type: string
        targetSystem:
          description: Target system to dispatch to
          enum:
            - JIRA
            - SERVICENOW
            - WEBHOOK
            - MANUAL
          examples:
            - MANUAL
          maxLength: 255
          minLength: 1
          type: string
      required:
        - exceptionIds
        - targetSystem
      type: object
    BulkFailure:
      additionalProperties: false
      properties:
        code:
          description: Stable product error code for this row, when the failure has one
          examples:
            - MTCH-0514
          type: string
        error:
          description: Human-readable reason the exception could not be processed
          examples:
            - exception not found
          type: string
        exceptionId:
          description: Identifier of the exception that failed (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
      required:
        - exceptionId
        - error
      type: object
    BulkResolveRequest:
      additionalProperties: false
      properties:
        exceptionIds:
          description: Exception IDs to resolve
          items:
            format: uuid
            type: string
          maxItems: 100
          minItems: 1
          type:
            - array
            - "null"
        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:
        - exceptionIds
        - resolution
      type: object
    CandidateFieldResponse:
      additionalProperties: false
      properties:
        canonicalKey:
          description: Canonical field-map key. The closed vocabulary is the required keys (external_id, amount, currency, date) plus the optional ones (description, fee_amount, fee_currency); the extractor drops any key outside it before a candidate is persisted
          enum:
            - external_id
            - amount
            - currency
            - date
            - description
            - fee_amount
            - fee_currency
          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
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
            - FUZZY
          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)"
          enum:
            - text_layer
            - vision
          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
    CashImpactSummaryResponse:
      additionalProperties: false
      properties:
        byAge:
          description: Unreconciled exposure broken down by age bucket.
          items:
            $ref: "#/components/schemas/AgeExposureResponse"
          type:
            - array
            - "null"
        byCurrency:
          description: Unreconciled exposure broken down by currency.
          items:
            $ref: "#/components/schemas/CurrencyExposureResponse"
          type:
            - array
            - "null"
        totalUnmatchedAmount:
          description: Total unreconciled monetary exposure across all currencies, as a decimal string.
          examples:
            - "70000.00"
          type: string
      required:
        - totalUnmatchedAmount
        - byCurrency
        - byAge
      type: object
    CloneContextRequest:
      additionalProperties: false
      properties:
        includeRules:
          description: Whether to clone match rules and fee rules. Defaults to true when omitted.
          examples:
            - true
          type: boolean
        includeSources:
          description: Whether to clone sources and their field maps. Defaults to true when omitted.
          examples:
            - true
          type: boolean
        name:
          description: Name for the newly cloned context.
          examples:
            - Bank Reconciliation Q1 (Copy)
          maxLength: 100
          minLength: 1
          type: string
      required:
        - name
      type: object
    CloneContextResponse:
      additionalProperties: false
      properties:
        context:
          $ref: "#/components/schemas/ReconciliationContextResponse"
          description: The newly created context.
        feeRulesCloned:
          description: Number of fee rules cloned into the new context.
          examples:
            - 2
          format: int64
          type: integer
        fieldMapsCloned:
          description: Number of field maps cloned into the new context.
          examples:
            - 3
          format: int64
          type: integer
        rulesCloned:
          description: Number of match rules cloned into the new context.
          examples:
            - 5
          format: int64
          type: integer
        sourcesCloned:
          description: Number of sources cloned into the new context.
          examples:
            - 3
          format: int64
          type: integer
      required:
        - context
        - sourcesCloned
        - rulesCloned
        - feeRulesCloned
        - fieldMapsCloned
      type: object
    CloseDisputeRequest:
      additionalProperties: false
      properties:
        resolution:
          description: Resolution description
          examples:
            - Counterparty acknowledged the error and issued correction
          maxLength: 5000
          minLength: 1
          type: string
        won:
          description: Whether the dispute was won
          examples:
            - true
          type: boolean
      required:
        - won
        - resolution
      type: object
    CommentResponse:
      additionalProperties: false
      properties:
        author:
          description: Author of the comment
          examples:
            - user@example.com
          type: string
        content:
          description: Comment content
          examples:
            - This transaction needs review.
          type: string
        createdAt:
          description: Creation timestamp as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        exceptionId:
          description: Identifier of the exception this comment belongs to (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
          type: string
        id:
          description: Unique identifier for the comment (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        updatedAt:
          description: Last update timestamp as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - exceptionId
        - author
        - content
        - createdAt
        - updatedAt
      type: object
    ConnectionListResponse:
      additionalProperties: false
      properties:
        connections:
          description: Discovered connections scoped to the current tenant
          items:
            $ref: "#/components/schemas/ConnectionResponse"
          type:
            - array
            - "null"
      required:
        - connections
      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
    ConnectionResponse:
      additionalProperties: false
      properties:
        baseURL:
          description: Per-connection API base URL of a REST connector connection; absent when the deployment default applies and for database connectors
          examples:
            - https://sandbox.provider.example
          format: uri
          type: string
        configName:
          description: Connection configuration name
          examples:
            - prod-ledger-db
          type: string
        databaseName:
          description: Database name
          examples:
            - ledger
          type: string
        databaseType:
          description: Database engine type (canonical engine token as stored)
          examples:
            - POSTGRESQL
          type: string
        host:
          description: Database host; empty for REST connector connections, whose service address is reported as baseURL
          examples:
            - db.internal.example.com
          type: string
        id:
          description: Internal Matcher connection identifier
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        lastSeenAt:
          description: Timestamp the connection was last observed healthy (RFC 3339)
          examples:
            - "2026-06-17T14:32:05Z"
          format: date-time
          type: string
        port:
          description: Database port
          examples:
            - 5432
          format: int64
          type: integer
        schema:
          description: Schema/namespace within the database, when set
          examples:
            - public
          type: string
        schemaDiscovered:
          description: Whether table schemas have been discovered for this connection
          type: boolean
        status:
          description: Current lifecycle status of the connection as reported by the extraction engine
          examples:
            - available
          type: string
        userName:
          description: Database user name the connection authenticates as
          examples:
            - matcher_ro
          type: string
      required:
        - id
        - configName
        - databaseType
        - host
        - port
        - databaseName
        - userName
        - status
        - schemaDiscovered
        - lastSeenAt
      type: object
    ConnectionSchemaHistoryResponse:
      additionalProperties: false
      properties:
        connectionId:
          description: Internal Matcher connection identifier the history belongs to
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        generations:
          description: Prior generations of the schema map, oldest first; empty when the map has never changed
          items:
            $ref: "#/components/schemas/SchemaGenerationResponse"
          type:
            - array
            - "null"
      required:
        - connectionId
        - generations
      type: object
    ConnectionSchemaResponse:
      additionalProperties: false
      properties:
        connectionId:
          description: Internal Matcher connection identifier the schema belongs to
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        fieldReport:
          description: "How the field lists in this map were obtained, recorded per row by the report that produced it and folded to one answer for the map: ENUMERATED means they come from the source's own catalog and are exhaustive for the credential that read it, so fewer fields than before is a real change in what the source reports; SAMPLED means they are inferred from a sample of the source's data (MongoDB reads the union of top-level keys over $sample-d documents), so they vary between reads with nothing changed at the source and no reduction is ever asserted from them — how the persisted field lists then build up, and what ends that, is stated in full in this operation's description. It is NEVER derived from this connection's current databaseType, which an operator can edit: a retype must not re-attribute field sets a different connector produced. Present only when every row of the map records the same kind: absent when the rows disagree, when any of them predates the recording of this fact, and when the probe that installed them could not show which connector produced its snapshot — in each case nothing is asserted about how the fields were obtained. It is the fact that separates routes (1) and (5) of notYetExtractableReason, whose remedies contradict each other"
          enum:
            - ENUMERATED
            - SAMPLED
          examples:
            - SAMPLED
          type: string
        lastKnownMap:
          description: "The tables are a retired generation, not the connection's live map: the source has not re-asserted them since they were archived. Absent when the rows served are live"
          type: boolean
        lastReadAt:
          description: When the map was last successfully read from the source; absent when no map has ever been read
          examples:
            - "2026-07-26T14:03:00Z"
          format: date-time
          type: string
        notYetExtractableReason:
          description: "Why nothing in this map can be extracted from yet; absent when at least one table can. COLUMNS_NOT_ENUMERATED means Matcher holds no confirmed column observation for this connection that it could project into an extraction, and it arrives by five routes worth distinguishing, each named here so a client can tie an operator-facing sentence to one: (1) TABLES_WITHOUT_COLUMNS — every persisted table carries no column, the only route visible in the tables below; (2) COLUMNS_NEVER_CONFIRMED — no probe of this connection ever recorded a confirmed-columns observation, in which case the tables below may still show columns; (3) COLUMN_VISIBILITY_LOST — an established connection whose source enumerates its columns from a catalog returned columns for no table it still names, so that snapshot was refused and the tables below show their last confirmed columns; (4) NO_TABLES_NAMED — the source named no table at all; (5) SAMPLED_REPORT_NO_FIELDS — the source's field list is sampled from its data rather than enumerated from a catalog and the draw returned no field, so nothing was refused: the tables installed, no column was confirmed, and extraction reopens as soon as a draw returns fields. Routes 3, 4 and 5 arrive as the same response and a client states them as readings rather than picking one. Routes 1 and 5 also arrive as the same response — a map in which every table carries no column — and their remedies contradict each other, so fieldReport above says which of the two applies: SAMPLED is route 5 and no grant is involved, ENUMERATED is route 1 and the credential's column grants are the thing to check. Both must be stated when fieldReport is absent, which happens when the rows of this map disagree about how their field lists were obtained, when any of them predates the recording of that fact, or when the probe that installed them could not show which connector produced its snapshot — the connector registry is not consulted on this path at all, so a registered connector is neither what makes the kind present nor what its absence says anything about. No route distinguishes a source with no columns to give from columns this connection's credential can no longer read"
          enum:
            - COLUMNS_NOT_ENUMERATED
          examples:
            - COLUMNS_NOT_ENUMERATED
          type: string
        tables:
          description: All discovered table schemas for the connection; the last known map even when the connection is unreachable
          items:
            $ref: "#/components/schemas/SchemaTableResponse"
          type:
            - array
            - "null"
        unreachable:
          description: "The connection could not be reached when this map was served: the tables are the last known map and may no longer match the source"
          type: boolean
      required:
        - connectionId
        - tables
      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
        requiredFields:
          description: Credential field names a REST-category connector requires at provisioning time, in render order; absent for database connectors
          items:
            type: string
          type:
            - array
            - "null"
        type:
          description: Canonical engine datasource-type token
          examples:
            - POSTGRESQL
          type: string
      required:
        - type
        - category
      type: object
    CreateAdjustmentRequest:
      additionalProperties: false
      properties:
        amount:
          description: Adjustment amount (decimal string)
          examples:
            - "10.50"
          minLength: 1
          type: string
        currency:
          description: ISO 4217 currency code
          examples:
            - USD
          maxLength: 3
          minLength: 3
          type: string
        description:
          description: Human-readable description
          examples:
            - Bank wire fee adjustment
          minLength: 1
          type: string
        direction:
          description: Adjustment direction
          enum:
            - DEBIT
            - CREDIT
          examples:
            - DEBIT
          type: string
        matchGroupId:
          description: Match group the adjustment balances (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        reason:
          description: Reason for the adjustment
          examples:
            - Variance due to bank processing fee
          minLength: 1
          type: string
        transactionId:
          description: Single transaction the adjustment balances (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        type:
          description: Adjustment type
          enum:
            - BANK_FEE
            - FX_DIFFERENCE
            - ROUNDING
            - WRITE_OFF
            - MISCELLANEOUS
          examples:
            - BANK_FEE
          type: string
      required:
        - type
        - direction
        - amount
        - currency
        - description
        - reason
      type: object
    CreateContextRequest:
      additionalProperties: false
      properties:
        agedBreakCalendar:
          description: Business-day calendar the aging threshold is measured against (e.g. US_FED, BR_ANBIMA). Omit/empty measures the age in raw calendar days.
          examples:
            - BR_ANBIMA
          type: string
        agedBreakThresholdDays:
          description: Open-item aging SLA in business days. An open-item residual older than this surfaces as an AGED_BREAK exception during the match run. Omit to disable aging for the context.
          examples:
            - 30
          format: int64
          type: integer
        autoMatchOnUpload:
          description: When true, a match run is triggered automatically after a file upload completes.
          examples:
            - false
          type: boolean
        feeNormalization:
          description: Fee normalization mode. NET compares amounts after fees are deducted; GROSS compares amounts before fees.
          enum:
            - NET
            - GROSS
          examples:
            - NET
          type: string
        feeToleranceAbs:
          description: Absolute fee tolerance as a decimal string in the context currency.
          examples:
            - "0.01"
          type: string
        feeTolerancePct:
          description: Percentage fee tolerance as a decimal string (0.5 means 0.5%).
          examples:
            - "0.5"
          type: string
        interval:
          description: Execution interval label for the context (e.g. daily, weekly).
          examples:
            - daily
          maxLength: 100
          minLength: 1
          type: string
        name:
          description: Human-readable name of the reconciliation context.
          examples:
            - Bank Reconciliation Q1
          maxLength: 100
          minLength: 1
          type: string
        rules:
          description: Match rules to create inline with the context.
          items:
            $ref: "#/components/schemas/CreateMatchRuleRequest"
          maxItems: 50
          type:
            - array
            - "null"
        signConvention:
          description: "How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles. Defaults to SAME. In 1:N contexts only payments of the declared sign are allocated to an invoice, and in N:M contexts a short-paid invoice keeps an open balance only when it is positive under SAME, or when the rule's sign mode is opposite under OPPOSITE; any other short payment stays unmatched; a carried open balance settles on a payment of the declared sign or on a reversal from the invoice's own side, and a row from an archived source stays unmatched. It cannot change once the context has carried a partial balance, or while a match run is in progress."
          enum:
            - SAME
            - OPPOSITE
          examples:
            - SAME
          type: string
        sources:
          description: Sources to create inline with the context.
          items:
            $ref: "#/components/schemas/CreateContextSourceRequest"
          maxItems: 10
          type:
            - array
            - "null"
        type:
          description: Reconciliation topology. 1:1 matches one left transaction to one right transaction; 1:N matches one transaction against many on the other side; N:M matches groups on both sides.
          enum:
            - "1:1"
            - 1:N
            - N:M
          examples:
            - "1:1"
          type: string
      required:
        - name
        - type
        - interval
      type: object
    CreateContextSourceRequest:
      additionalProperties: false
      properties:
        config:
          additionalProperties: {}
          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
          properties:
            blank_external_id:
              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
              enum:
                - REJECT
                - NEEDS_REVIEW
              type: string
            camt053:
              additionalProperties: false
              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
              properties:
                date_basis:
                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
                  enum:
                    - booking
                    - valuation
                  type: string
                external_id_source:
                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
                  enum:
                    - ntry_ref
                    - end_to_end_id
                    - tx_id
                  type: string
              type: object
            dialect:
              additionalProperties: false
              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
              properties:
                date_style:
                  enum:
                    - iso
                    - iso_offset
                    - dmy
                    - mdy
                  type: string
                decimal_style:
                  description: dot is 1234.56, comma is 1.234,56.
                  enum:
                    - dot
                    - comma
                  type: string
                delimiter:
                  enum:
                    - comma
                    - semicolon
                    - tab
                    - pipe
                  type: string
                encoding:
                  enum:
                    - utf-8
                    - utf-8-sig
                    - cp1252
                    - iso-8859-1
                  type: string
              type: object
            duplicate_key:
              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
              items:
                enum:
                  - external_id
                  - amount
                  - currency
                  - date
                  - description
                  - fee_amount
                  - fee_currency
                type: string
              minItems: 1
              type: array
              uniqueItems: true
            duplicate_policy:
              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
              enum:
                - FLAG_AS_EXCEPTION
                - KEEP_FIRST
                - REJECT
              type: string
            fail_on_error_rate_percent:
              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
              maximum: 99
              minimum: 1
              type: integer
          type: object
        mapping:
          additionalProperties: {}
          description: Optional field-mapping object normalizing source columns to canonical transaction fields.
          type: object
        name:
          description: Human-readable name of the source.
          examples:
            - Primary Bank Account
          maxLength: 50
          minLength: 1
          type: string
        side:
          description: Matching side this source feeds. LEFT and RIGHT are the two sides reconciled against each other.
          enum:
            - LEFT
            - RIGHT
          examples:
            - LEFT
          type: string
        type:
          description: Origin of the source data. LEDGER is the internal ledger; BANK is a bank statement feed; GATEWAY is a payment gateway; CUSTOM is a bespoke feed; FETCHER is a discovery-engine pull.
          enum:
            - LEDGER
            - BANK
            - GATEWAY
            - CUSTOM
            - FETCHER
          examples:
            - BANK
          type: string
      required:
        - name
        - type
        - side
      type: object
    CreateExportJobRequest:
      additionalProperties: false
      properties:
        dateFrom:
          description: "Start date (YYYY-MM-DD). Optional: defaults to 30 days before dateTo."
          examples:
            - "2025-01-01"
          format: date
          type: string
        dateTo:
          description: "End date (YYYY-MM-DD). Optional: defaults to tomorrow (UTC)."
          examples:
            - "2025-01-31"
          format: date
          type: string
        format:
          description: Export file format (uppercase only).
          enum:
            - CSV
            - JSON
            - XML
          examples:
            - CSV
          type: string
        reportType:
          description: Report type to export (uppercase only).
          enum:
            - MATCHED
            - UNMATCHED
            - SUMMARY
            - VARIANCE
            - EXCEPTIONS
            - MATCHES
            - UNMATCHED_TRANSACTIONS
          examples:
            - MATCHED
          type: string
        sourceId:
          description: Optional source ID filter (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
      required:
        - reportType
        - format
      type: object
    CreateExportJobResponse:
      additionalProperties: false
      properties:
        jobId:
          description: Identifier of the newly created export job (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        status:
          description: Initial status of the job; always QUEUED on creation.
          enum:
            - QUEUED
          examples:
            - QUEUED
          type: string
        statusUrl:
          description: Relative URL to poll for this job's status.
          examples:
            - /v1/export-jobs/550e8400-e29b-41d4-a716-446655440001
          type: string
      required:
        - jobId
        - status
        - statusUrl
      type: object
    CreateFeeRuleRequest:
      additionalProperties: false
      properties:
        feeScheduleId:
          description: UUID of the fee schedule this rule applies when its predicates match.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        name:
          description: Human-readable name of the fee rule.
          examples:
            - BB Right-Side Rule
          maxLength: 100
          minLength: 1
          type: string
        predicates:
          description: Predicates (ANDed together) that a transaction's metadata must satisfy for this rule to apply.
          items:
            $ref: "#/components/schemas/FieldPredicateRequest"
          type:
            - array
            - "null"
        priority:
          description: Evaluation priority; lower numbers are evaluated first. Must be unique within the context. LEFT, RIGHT, and ANY rules share the same priority space.
          examples:
            - 0
          format: int64
          type: integer
        side:
          description: Side the rule applies to. LEFT and RIGHT target one reconciliation side; ANY matches transactions on either side.
          enum:
            - LEFT
            - RIGHT
            - ANY
          examples:
            - RIGHT
          type: string
      required:
        - side
        - feeScheduleId
        - name
        - priority
        - predicates
      type: object
    CreateFeeScheduleItemRequest:
      additionalProperties: false
      properties:
        name:
          description: Human-readable name of the fee item.
          examples:
            - interchange
          type: string
        priority:
          description: Application order within the schedule; relevant for CASCADING application.
          examples:
            - 1
          format: int64
          type: integer
        structure:
          additionalProperties: {}
          description: "Type-specific structure. FLAT: {\"amount\":\"1.50\"}. PERCENTAGE: {\"rate\":\"0.029\"} where rate is a 0..1 fraction of the base amount (0.029 means 2.9%), not a percent value. TIERED: {\"tiers\":[{\"rate\":\"0.01\",\"upTo\":\"1000\"},...]} with the same 0..1 fraction semantics per tier rate. EXPRESSION: {\"expression\":\"gross - desconto + multa + juros_dia * days_late(due_date, pay_date)\"} a formula over metadata fields (+ - * /, parentheses, and the functions days_late, days_between, max, min, abs, clamp). A formula that is only the base amount times numeric literals is a percentage rate and is bounded 0..1: gross * 0.029 is 2.9%, gross * 2.9 is refused; any other formula is unbounded."
          type: object
        structureType:
          description: Shape of the fee structure; the structure field documents the object each one takes.
          enum:
            - FLAT
            - PERCENTAGE
            - TIERED
            - EXPRESSION
          examples:
            - PERCENTAGE
          type: string
      required:
        - name
        - priority
        - structureType
        - structure
      type: object
    CreateFeeScheduleRequest:
      additionalProperties: false
      properties:
        applicationOrder:
          description: How items combine. PARALLEL applies every item to the same gross base; CASCADING applies each item to the net remaining after prior items.
          enum:
            - PARALLEL
            - CASCADING
          examples:
            - PARALLEL
          type: string
        currency:
          description: ISO 4217 currency code the schedule's amounts are denominated in.
          examples:
            - USD
          type: string
        items:
          description: Fee items that make up the schedule; at least one is required.
          items:
            $ref: "#/components/schemas/CreateFeeScheduleItemRequest"
          maxItems: 100
          minItems: 1
          type:
            - array
            - "null"
        name:
          description: Human-readable name of the fee schedule.
          examples:
            - Card Processing - Visa
          maxLength: 100
          minLength: 1
          type: string
        roundingMode:
          description: Rounding strategy. HALF_UP rounds halves away from zero; BANKERS rounds halves to the nearest even digit; FLOOR rounds down; CEIL rounds up; TRUNCATE drops extra digits.
          enum:
            - HALF_UP
            - BANKERS
            - FLOOR
            - CEIL
            - TRUNCATE
          examples:
            - HALF_UP
          type: string
        roundingScale:
          description: Number of decimal places fee amounts are rounded to.
          examples:
            - 2
          format: int64
          type: integer
      required:
        - name
        - currency
        - applicationOrder
        - roundingScale
        - roundingMode
        - items
      type: object
    CreateFieldMapRequest:
      additionalProperties: false
      properties:
        mapping:
          additionalProperties: {}
          description: Field-mapping object that normalizes a source's raw columns to canonical transaction fields.
          type: object
      required:
        - mapping
      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
    CreateManualMatchRequest:
      additionalProperties: false
      properties:
        notes:
          description: Optional note for the manual match
          type: string
        transactionIds:
          description: Transaction IDs to link (UUIDs)
          examples:
            -   - 550e8400-e29b-41d4-a716-446655440000
          items:
            type: string
          maxItems: 50
          minItems: 2
          type:
            - array
            - "null"
      required:
        - transactionIds
      type: object
    CreateMatchRuleRequest:
      additionalProperties: false
      properties:
        config:
          additionalProperties: {}
          description: "Rule-specific configuration object. Includes the built-in toggles (matchAmount, matchCurrency, matchDate, matchReference) and tolerance/lag parameters, plus an optional composite-key array matchFields: [{ field, mode, tolerance? }] where mode is one of required, conditional, or off, and tolerance is an optional per-field relaxation ({ absTolerance?, percentTolerance? } for numeric or { stringMode: exact|fold } for text). Optional date keys (opt-in; default behavior is raw UTC days): timezone (an IANA zone name, e.g. America/Sao_Paulo, buckets dates by local sales-day before the date window/lag is applied), calendar (a vendored business-day calendar name, US_FED or BR_ANBIMA — on TOLERANCE it makes dateWindowDays count business days; on DATE_LAG it pairs with businessDayMode), and businessDayMode (DATE_LAG only; makes minDays/maxDays count business days under calendar). Optional signMode key (one of same, opposite, ignore; default same) selects the axis used when the rule compares amounts: same matches signed amounts (legacy behavior); opposite matches a value against its negation (a -100 refund reconciles against a +100 charge); ignore compares magnitudes only. It is consulted only when the rule actually compares amounts (matchAmount on EXACT/FUZZY, the tolerance band on TOLERANCE); on a rule that does not compare amounts it is accepted but inert."
          type: object
        priority:
          description: Execution priority; lower numbers run first. Must be unique within the context.
          examples:
            - 1
          format: int64
          maximum: 1000
          minimum: 1
          type: integer
        type:
          description: Matching strategy. EXACT requires identical field values; TOLERANCE allows configured numeric slack; DATE_LAG allows a configured date offset between sides; FUZZY matches on normalized/similarity-scored references (free-text memos, truncated refs) and always proposes for review (never auto-confirms).
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
            - FUZZY
          examples:
            - EXACT
          type: string
      required:
        - priority
        - type
        - config
      type: object
    CreateScheduleRequest:
      additionalProperties: false
      properties:
        cronExpression:
          description: Cron expression (5-field) defining when the reconciliation runs.
          examples:
            - 0 0 * * *
          maxLength: 100
          minLength: 1
          type: string
        enabled:
          description: Whether the schedule is active. Defaults to true when omitted.
          examples:
            - true
          type: boolean
      required:
        - cronExpression
      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.
          examples:
            - 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
    CreateSourceRequest:
      additionalProperties: false
      properties:
        config:
          additionalProperties: {}
          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
          properties:
            blank_external_id:
              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
              enum:
                - REJECT
                - NEEDS_REVIEW
              type: string
            camt053:
              additionalProperties: false
              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
              properties:
                date_basis:
                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
                  enum:
                    - booking
                    - valuation
                  type: string
                external_id_source:
                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
                  enum:
                    - ntry_ref
                    - end_to_end_id
                    - tx_id
                  type: string
              type: object
            dialect:
              additionalProperties: false
              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
              properties:
                date_style:
                  enum:
                    - iso
                    - iso_offset
                    - dmy
                    - mdy
                  type: string
                decimal_style:
                  description: dot is 1234.56, comma is 1.234,56.
                  enum:
                    - dot
                    - comma
                  type: string
                delimiter:
                  enum:
                    - comma
                    - semicolon
                    - tab
                    - pipe
                  type: string
                encoding:
                  enum:
                    - utf-8
                    - utf-8-sig
                    - cp1252
                    - iso-8859-1
                  type: string
              type: object
            duplicate_key:
              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
              items:
                enum:
                  - external_id
                  - amount
                  - currency
                  - date
                  - description
                  - fee_amount
                  - fee_currency
                type: string
              minItems: 1
              type: array
              uniqueItems: true
            duplicate_policy:
              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
              enum:
                - FLAG_AS_EXCEPTION
                - KEEP_FIRST
                - REJECT
              type: string
            fail_on_error_rate_percent:
              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
              maximum: 99
              minimum: 1
              type: integer
          type: object
        name:
          description: Human-readable name of the source.
          examples:
            - Primary Bank Account
          maxLength: 50
          minLength: 1
          type: string
        side:
          description: Matching side this source feeds. LEFT and RIGHT are the two sides reconciled against each other.
          enum:
            - LEFT
            - RIGHT
          examples:
            - LEFT
          type: string
        type:
          description: Origin of the source data. LEDGER is the internal ledger; BANK is a bank statement feed; GATEWAY is a payment gateway; CUSTOM is a bespoke feed; FETCHER is a discovery-engine pull.
          enum:
            - LEDGER
            - BANK
            - GATEWAY
            - CUSTOM
            - FETCHER
          examples:
            - BANK
          type: string
      required:
        - name
        - type
        - side
      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
    CurrencyExposureResponse:
      additionalProperties: false
      properties:
        amount:
          description: Unreconciled monetary exposure in this currency, as a decimal string.
          examples:
            - "25000.00"
          type: string
        currency:
          description: ISO 4217 currency code for the exposure.
          examples:
            - USD
          type: string
        transactionCount:
          description: Number of unmatched transactions contributing to this currency's exposure.
          examples:
            - 250
          format: int64
          type: integer
      required:
        - currency
        - amount
        - transactionCount
      type: object
    CursorPagination:
      additionalProperties: false
      properties:
        next:
          type: string
        prev:
          type: string
      required:
        - next
        - prev
      type: object
    DashboardAggregatesResponse:
      additionalProperties: false
      properties:
        matchRate:
          $ref: "#/components/schemas/MatchRateStatsResponse"
          description: Match rate statistics for the window.
        sla:
          $ref: "#/components/schemas/SLAStatsResponse"
          description: SLA compliance statistics for the window.
        unmatchedByCurrency:
          description: Unreconciled exposure split by currency; the amounts sum to volume.unmatchedAmount. Empty when no transaction in the window is UNMATCHED or PENDING_REVIEW; always an array, never null. volume.unmatchedAmount is the engine's arithmetic sum of those amounts across currencies, so it is a meaningful money figure only when this split carries a single currency. Clients must not render it as money when the split names more than one currency.
          items:
            $ref: "#/components/schemas/CurrencyExposureResponse"
          type: array
        updatedAt:
          description: Timestamp when these aggregates were computed (RFC 3339, UTC).
          examples:
            - "2025-01-15T10:30:00Z"
          format: date-time
          type: string
        volume:
          $ref: "#/components/schemas/VolumeStatsResponse"
          description: Transaction volume statistics for the window.
      required:
        - volume
        - matchRate
        - sla
        - unmatchedByCurrency
        - updatedAt
      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
        upstream:
          $ref: "#/components/schemas/Upstream"
          description: "RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one."
      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)"
          enum:
            - iso
            - iso_offset
            - dmy
            - mdy
          examples:
            - iso
          type: string
        decimalStyle:
          description: "Detected amount decimal convention: dot (1234.56) or comma (1234,56)"
          enum:
            - dot
            - comma
          examples:
            - comma
          type: string
        delimiter:
          description: "Detected CSV field separator: comma, semicolon, tab, or pipe"
          enum:
            - comma
            - semicolon
            - tab
            - 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"
          enum:
            - utf-8
            - utf-8-sig
            - cp1252
            - iso-8859-1
          examples:
            - utf-8
          type: string
      required:
        - encoding
        - delimiter
        - decimalStyle
        - dateStyle
      type: object
    DiscoveryStatusResponse:
      additionalProperties: false
      properties:
        connectionCount:
          description: Number of discovered connections currently cached for the tenant
          format: int64
          type: integer
        fetcherHealthy:
          type: boolean
        lastSyncAt:
          description: Timestamp of the last successful sync (RFC 3339); null if never synced
          examples:
            - "2026-06-17T14:32:05Z"
          format: date-time
          type: string
      required:
        - fetcherHealthy
        - connectionCount
      type: object
    DispatchRequest:
      additionalProperties: false
      properties:
        queue:
          description: Optional queue or team assignment
          examples:
            - RECON-TEAM
          maxLength: 255
          type: string
        targetSystem:
          description: Target system to dispatch to
          enum:
            - JIRA
            - SERVICENOW
            - WEBHOOK
            - MANUAL
          examples:
            - MANUAL
          maxLength: 255
          minLength: 1
          type: string
      required:
        - targetSystem
      type: object
    DispatchResponse:
      additionalProperties: false
      properties:
        acknowledged:
          description: Whether the target system acknowledged the dispatch
          examples:
            - true
          type: boolean
        dispatchedAt:
          description: Dispatch timestamp as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        exceptionId:
          description: Identifier of the exception that was dispatched (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        externalReference:
          description: Reference identifier returned by the target system
          examples:
            - RECON-1234
          type: string
        target:
          description: External target system the exception was dispatched to
          examples:
            - JIRA
          type: string
      required:
        - exceptionId
        - target
        - acknowledged
        - dispatchedAt
      type: object
    DisputeResponse:
      additionalProperties: false
      properties:
        category:
          description: "Dispute category: BANK_FEE_ERROR (incorrect fee), UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION, AMOUNT_MISMATCH, or OTHER"
          enum:
            - BANK_FEE_ERROR
            - UNRECOGNIZED_CHARGE
            - DUPLICATE_TRANSACTION
            - AMOUNT_MISMATCH
            - OTHER
          examples:
            - BANK_FEE_ERROR
          type: string
        createdAt:
          description: Creation timestamp as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        description:
          description: Description of the dispute
          examples:
            - Transaction amount differs from expected
          type: string
        evidence:
          description: Evidence items submitted for this dispute (max 50)
          items:
            $ref: "#/components/schemas/EvidenceResponse"
          maxItems: 50
          type:
            - array
            - "null"
        exceptionId:
          description: Identifier of the exception this dispute is for (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
          type: string
        id:
          description: Unique identifier for the dispute (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        openedBy:
          description: User who opened the dispute
          examples:
            - user@example.com
          type: string
        reopenReason:
          description: Reason recorded when the dispute was reopened
          examples:
            - New evidence discovered
          type: string
        resolution:
          description: Resolution description recorded when the dispute was closed
          examples:
            - Counterparty confirmed error
          type: string
        state:
          description: "Dispute state: DRAFT, OPEN, PENDING_EVIDENCE (awaiting evidence), WON, or LOST"
          enum:
            - DRAFT
            - OPEN
            - PENDING_EVIDENCE
            - WON
            - LOST
          examples:
            - OPEN
          type: string
        updatedAt:
          description: Last update timestamp as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - exceptionId
        - category
        - state
        - description
        - openedBy
        - createdAt
        - updatedAt
      type: object
    DownloadExportJobResponse:
      additionalProperties: false
      properties:
        downloadUrl:
          description: Presigned URL to download the export file.
          examples:
            - https://storage.example.com/exports/report.csv?token=abc
          type: string
        expiresIn:
          description: Number of seconds until the presigned download URL expires.
          examples:
            - 3600
          format: int64
          type: integer
        fileName:
          description: Original file name of the export.
          examples:
            - matched_report.csv
          type: string
        sha256:
          description: SHA-256 checksum of the file (hex-encoded) for integrity verification.
          examples:
            - e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
          type: string
      required:
        - downloadUrl
        - fileName
        - sha256
        - expiresIn
      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
    EvidenceResponse:
      additionalProperties: false
      properties:
        comment:
          description: Comment describing the evidence
          examples:
            - Bank statement attached
          type: string
        disputeId:
          description: Identifier of the dispute this evidence belongs to (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
          type: string
        fileUrl:
          description: Optional URL to the evidence file
          examples:
            - https://storage.example.com/evidence/doc123.pdf
          type: string
        id:
          description: Unique identifier for the evidence (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        submittedAt:
          description: Submission timestamp as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        submittedBy:
          description: User who submitted the evidence
          examples:
            - user@example.com
          type: string
      required:
        - id
        - disputeId
        - comment
        - submittedBy
        - submittedAt
      type: object
    ExceptionResponse:
      additionalProperties: false
      properties:
        amount:
          description: "Enrichment: the exception transaction's amount as a decimal string in the transaction's currency. Present on list rows and get-by-id when the transaction still exists."
          examples:
            - "1250.50"
          type: string
        assignedTo:
          description: User the exception is currently assigned to
          examples:
            - user@example.com
          type: string
        contextId:
          description: "Enrichment: id of the reconciliation context the exception's source belongs to (UUID). Present on list rows and get-by-id when the transaction and source still exist; powers the global triage queue's context attribution."
          examples:
            - 550e8400-e29b-41d4-a716-446655440004
          type: string
        createdAt:
          description: Creation timestamp as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        currency:
          description: "Enrichment: ISO 4217 currency code of the exception transaction's amount. Present on list rows and get-by-id when the transaction still exists."
          examples:
            - USD
          type: string
        dueAt:
          description: Resolution due date as an RFC 3339 timestamp
          examples:
            - "2025-01-20T10:30:00Z"
          type: string
        externalIssueId:
          description: Issue identifier in the external system, when dispatched
          examples:
            - RECON-1234
          type: string
        externalSystem:
          description: External system the exception was dispatched to, when applicable
          examples:
            - JIRA
          type: string
        id:
          description: Unique identifier for the exception (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        reason:
          description: Reason the exception was originally raised
          examples:
            - Amount mismatch detected
          type: string
        resolutionNotes:
          description: Free-text notes captured when the exception was resolved
          examples:
            - Resolved via force match
          type: string
        resolutionReason:
          description: Reason code recorded for the resolution
          examples:
            - BUSINESS_DECISION
          type: string
        resolutionType:
          description: "How the exception was resolved."
          examples:
            - FORCE_MATCH
          type: string
        resolvedAt:
          description: When the exception was resolved, as an RFC 3339 timestamp. Present only for RESOLVED exceptions.
          examples:
            - "2025-01-15T12:00:00Z"
          type: string
        resolvedBy:
          description: Principal that resolved the exception (JWT sub, or 'system' for automated callback resolutions). Empty until resolved or when the resolving path is un-attributed.
          examples:
            - user@example.com
          type: string
        runId:
          description: Identifier of the match run that LATEST surfaced this exception (UUID). Refreshed on every re-run that re-surfaces the break, so it names the most recent run that touched it; powers the run-precise jump from a run to its exceptions. Absent for legacy rows written before run linkage and for ingestion-minted duplicate-transaction breaks (not produced by a match run).
          examples:
            - 550e8400-e29b-41d4-a716-446655440002
          type: string
        settlement:
          $ref: "#/components/schemas/ExceptionSettlementResponse"
          description: Settlement figures for a fee break (expected vs credited and the signed difference), derived from the live fee-variance snapshot recorded for the exception's transaction. Present on get-by-id only, and only when the snapshot and the transaction amount are both available in the same currency.
        severity:
          description: "Severity level: LOW and MEDIUM are informational, HIGH needs prompt review, CRITICAL requires immediate action"
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
          examples:
            - HIGH
          type: string
        sourceId:
          description: "Enrichment: id of the reconciliation source the exception transaction belongs to (UUID). Present on list rows and get-by-id when the transaction still exists."
          examples:
            - 550e8400-e29b-41d4-a716-446655440003
          type: string
        sourceName:
          description: "Enrichment: display name of the reconciliation source. Present on get-by-id when the transaction and its source still exist."
          examples:
            - Bank feed
          type: string
        status:
          description: "Lifecycle status: OPEN (unhandled), ASSIGNED (owned by a user), PENDING_RESOLUTION (a resolution is in flight), RESOLVED (closed out)"
          enum:
            - OPEN
            - ASSIGNED
            - PENDING_RESOLUTION
            - RESOLVED
          examples:
            - OPEN
          type: string
        transactionDate:
          description: "Enrichment: the exception transaction's value date as an RFC 3339 timestamp. Present on list rows and get-by-id when the transaction still exists."
          examples:
            - "2025-01-14T00:00:00Z"
          type: string
        transactionId:
          description: Identifier of the transaction this exception was raised for (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
          type: string
        updatedAt:
          description: Last update timestamp as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - transactionId
        - severity
        - status
        - createdAt
        - updatedAt
      type: object
    ExceptionSettlementResponse:
      additionalProperties: false
      properties:
        credited:
          description: Amount actually credited (the transaction amount), as a decimal string
          examples:
            - "95.00"
          type: string
        currency:
          description: ISO 4217 currency code of the settlement amounts (the transaction's currency)
          examples:
            - BRL
          type: string
        difference:
          description: Signed difference credited minus expected, as a decimal string; negative when the credit fell short
          examples:
            - "-2.00"
          type: string
        expected:
          description: Amount the transaction should have credited under the expected fee, as a decimal string
          examples:
            - "97.00"
          type: string
      required:
        - expected
        - credited
        - difference
        - currency
      type: object
    ExportCountResponse:
      additionalProperties: false
      properties:
        count:
          description: Total number of rows matching the query; clients use this to choose between a synchronous download (<1000 rows) and an asynchronous export job (>=1000 rows).
          examples:
            - 4250
          format: int64
          type: integer
      required:
        - count
      type: object
    ExportJobListResponse:
      additionalProperties: false
      properties:
        hasMore:
          description: True when another page is available (nextCursor is non-empty).
          examples:
            - true
          type: boolean
        items:
          description: Export jobs in the current page, newest first.
          items:
            $ref: "#/components/schemas/ExportJobResponse"
          maxItems: 200
          type:
            - array
            - "null"
        limit:
          description: Page size applied to this response.
          examples:
            - 20
          format: int64
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          description: Opaque forward-only cursor; pass it as the cursor query param to fetch the next page. Empty when there are no further pages.
          examples:
            - eyJpZCI6IjEyMyJ9
          type: string
      required:
        - items
        - limit
        - hasMore
      type: object
    ExportJobResponse:
      additionalProperties: false
      properties:
        bytesWritten:
          description: Size of the export file in bytes.
          examples:
            - 524288
          format: int64
          type: integer
        contextId:
          description: Identifier of the reconciliation context this export was queued for (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        createdAt:
          description: Timestamp when the job was created (RFC 3339, UTC).
          examples:
            - "2025-01-15T10:30:00Z"
          format: date-time
          type: string
        downloadUrl:
          description: Presigned download URL, present only when the job has succeeded and the file is still available.
          examples:
            - https://storage.example.com/exports/matched_report.csv?token=abc
          type: string
        error:
          description: Failure reason, present only when the job status is FAILED.
          examples:
            - timeout exceeded
          type: string
        expiresAt:
          description: Timestamp after which the export file is purged and no longer downloadable (RFC 3339, UTC).
          examples:
            - "2025-01-16T10:30:00Z"
          format: date-time
          type: string
        fileName:
          description: Generated export file name, present once the job has produced a file.
          examples:
            - matched_report_2025-01-31.csv
          type: string
        finishedAt:
          description: Timestamp when processing finished, present once the job reaches a terminal state (RFC 3339, UTC).
          examples:
            - "2025-01-15T10:35:00Z"
          format: date-time
          type: string
        format:
          description: File format of the exported report.
          enum:
            - CSV
            - JSON
            - XML
            - PDF
          examples:
            - CSV
          type: string
        id:
          description: Identifier of the export job (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        recordsWritten:
          description: Number of records written to the export file.
          examples:
            - 4250
          format: int64
          type: integer
        reportType:
          description: Type of report this job exports.
          enum:
            - MATCHED
            - UNMATCHED
            - SUMMARY
            - VARIANCE
            - EXCEPTIONS
            - MATCHES
            - UNMATCHED_TRANSACTIONS
          examples:
            - MATCHED
          type: string
        startedAt:
          description: Timestamp when processing started, present once the job has begun running (RFC 3339, UTC).
          examples:
            - "2025-01-15T10:30:05Z"
          format: date-time
          type: string
        status:
          description: "Current lifecycle status: QUEUED (waiting), RUNNING (in progress), SUCCEEDED (complete and downloadable), FAILED (errored), EXPIRED (file no longer available), CANCELED (cancelled by user)."
          enum:
            - QUEUED
            - RUNNING
            - SUCCEEDED
            - FAILED
            - EXPIRED
            - CANCELED
          examples:
            - SUCCEEDED
          type: string
      required:
        - id
        - contextId
        - reportType
        - format
        - status
        - recordsWritten
        - bytesWritten
        - createdAt
        - expiresAt
      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)
          enum:
            - PENDING_REVIEW
          examples:
            - PENDING_REVIEW
          type: string
      required:
        - reviewId
        - candidateCount
        - status
      type: object
    ExtractionFilters:
      additionalProperties: false
      properties:
        equals:
          additionalProperties:
            type: string
          type: object
      type: object
    ExtractionRequestResponse:
      additionalProperties: false
      properties:
        connectionId:
          description: Connection the extraction runs against
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        createdAt:
          description: Timestamp the extraction request was created (RFC 3339)
          examples:
            - "2026-06-17T14:32:05Z"
          format: date-time
          type: string
        endDate:
          description: Inclusive end date of the extracted range (RFC 3339)
          examples:
            - "2026-06-30"
          type: string
        errorMessage:
          description: Sanitized error message when the extraction failed; empty otherwise
          type: string
        filters:
          $ref: "#/components/schemas/ExtractionFilters"
          description: Extraction filters applied to the request, when set
        id:
          description: Internal extraction request identifier
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        ingestionJobId:
          description: Ingestion job created from the extracted data, once available
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        startDate:
          description: Inclusive start date of the extracted range (RFC 3339)
          examples:
            - "2026-06-01"
          type: string
        status:
          description: Current lifecycle status of the extraction request
          examples:
            - pending
          type: string
        tables:
          additionalProperties:
            $ref: "#/components/schemas/ExtractionTableResponse"
          description: Per-table extraction configuration keyed by table name
          type: object
        updatedAt:
          description: Timestamp the extraction request was last updated (RFC 3339)
          examples:
            - "2026-06-17T14:32:05Z"
          format: date-time
          type: string
      required:
        - id
        - connectionId
        - tables
        - status
        - createdAt
        - updatedAt
      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)"
          enum:
            - PENDING_REVIEW
            - APPROVED
            - REJECTED
          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
    ExtractionTableRequest:
      additionalProperties: false
      properties:
        columns:
          description: Optional explicit column projection; empty extracts all columns
          items:
            type: string
          type:
            - array
            - "null"
      type: object
    ExtractionTableResponse:
      additionalProperties: false
      properties:
        columns:
          description: Explicit column projection extracted for this table; empty means all columns
          items:
            type: string
          type:
            - array
            - "null"
      type: object
    FeeRuleResponse:
      additionalProperties: false
      properties:
        contextId:
          description: Identifier of the context the rule 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
        feeScheduleId:
          description: Identifier of the fee schedule this rule applies.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        id:
          description: Unique identifier of the fee rule.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        name:
          description: Human-readable name of the fee rule.
          examples:
            - BB Right-Side Rule
          type: string
        predicates:
          description: Predicates (ANDed together) that a transaction's metadata must satisfy for this rule to apply.
          items:
            $ref: "#/components/schemas/FieldPredicateResponse"
          type:
            - array
            - "null"
        priority:
          description: Evaluation priority; lower numbers are evaluated first.
          examples:
            - 0
          format: int64
          type: integer
        side:
          description: Side the rule applies to. LEFT and RIGHT target one reconciliation side; ANY matches transactions on either side.
          enum:
            - LEFT
            - RIGHT
            - ANY
          examples:
            - RIGHT
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - contextId
        - side
        - feeScheduleId
        - name
        - priority
        - predicates
        - createdAt
        - updatedAt
      type: object
    FeeScheduleItemResponse:
      additionalProperties: false
      properties:
        createdAt:
          description: Creation timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        id:
          description: Unique identifier of the fee item.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        name:
          description: Human-readable name of the fee item.
          examples:
            - interchange
          type: string
        priority:
          description: Application order within the schedule; relevant for CASCADING application.
          examples:
            - 1
          format: int64
          type: integer
        structure:
          additionalProperties: {}
          description: "Type-specific structure. FLAT: {\"amount\":\"1.50\"}. PERCENTAGE: {\"rate\":\"0.029\"} where rate is a 0..1 fraction of the base amount (0.029 means 2.9%), not a percent value. TIERED: {\"tiers\":[{\"rate\":\"0.01\",\"upTo\":\"1000\"},...]} with the same 0..1 fraction semantics per tier rate. EXPRESSION: {\"expression\":\"gross - desconto + multa + juros_dia * days_late(due_date, pay_date)\"} a formula over metadata fields (+ - * /, parentheses, and the functions days_late, days_between, max, min, abs, clamp). A formula that is only the base amount times numeric literals is a percentage rate and is bounded 0..1: gross * 0.029 is 2.9%, gross * 2.9 is refused; any other formula is unbounded."
          type: object
        structureType:
          description: Shape of the fee structure. FLAT is a fixed amount; PERCENTAGE is a rate of the base; TIERED applies different rates per amount tier; EXPRESSION computes the fee from a bounded arithmetic formula over transaction metadata.
          enum:
            - FLAT
            - PERCENTAGE
            - TIERED
            - EXPRESSION
          examples:
            - PERCENTAGE
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - name
        - priority
        - structureType
        - structure
        - createdAt
        - updatedAt
      type: object
    FeeScheduleResponse:
      additionalProperties: false
      properties:
        applicationOrder:
          description: How items combine. PARALLEL applies every item to the same gross base; CASCADING applies each item to the net remaining after prior items.
          enum:
            - PARALLEL
            - CASCADING
          examples:
            - PARALLEL
          type: string
        createdAt:
          description: Creation timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        currency:
          description: ISO 4217 currency code the schedule's amounts are denominated in.
          examples:
            - USD
          type: string
        id:
          description: Unique identifier of the fee schedule.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        items:
          description: Fee items that make up the schedule.
          items:
            $ref: "#/components/schemas/FeeScheduleItemResponse"
          maxItems: 100
          type:
            - array
            - "null"
        name:
          description: Human-readable name of the fee schedule.
          examples:
            - Card Processing - Visa
          type: string
        roundingMode:
          description: Rounding strategy. HALF_UP rounds halves away from zero; BANKERS rounds halves to the nearest even digit; FLOOR rounds down; CEIL rounds up; TRUNCATE drops extra digits.
          enum:
            - HALF_UP
            - BANKERS
            - FLOOR
            - CEIL
            - TRUNCATE
          examples:
            - HALF_UP
          type: string
        roundingScale:
          description: Number of decimal places fee amounts are rounded to.
          examples:
            - 2
          format: int64
          type: integer
        tenantId:
          description: Identifier of the tenant that owns the schedule.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        usedByContexts:
          description: Number of distinct contexts whose fee rules reference this schedule. Computed at read time from the fee rules that reference this schedule (never persisted).
          examples:
            - 2
          format: int64
          type: integer
      required:
        - id
        - tenantId
        - name
        - currency
        - applicationOrder
        - roundingScale
        - roundingMode
        - items
        - usedByContexts
        - 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
          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
    FieldMapResponse:
      additionalProperties: false
      properties:
        contextId:
          description: Identifier of the context this field map 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
        id:
          description: Unique identifier of the field map.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        mapping:
          additionalProperties: {}
          description: Field-mapping object normalizing the source's raw columns to canonical transaction fields.
          type: object
        sourceId:
          description: Identifier of the source this field map normalizes.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        version:
          description: Monotonic mutation counter incremented server-side on each field-map change. Read-only on the write path and NOT honored for optimistic concurrency control.
          examples:
            - 1
          format: int64
          type: integer
      required:
        - id
        - contextId
        - sourceId
        - mapping
        - version
        - createdAt
        - updatedAt
      type: object
    FieldPredicateRequest:
      additionalProperties: false
      properties:
        field:
          description: Transaction metadata field the predicate tests.
          examples:
            - institution
          type: string
        operator:
          description: Comparison operator. EQUALS matches a single value; NEQ is its negation (numeric when both sides parse as decimals, else case-insensitive string). IN matches any value in the values list. EXISTS asserts the field is present (no value needed). GT/GTE/LT/LTE compare the field numerically against a single decimal value. BETWEEN tests inclusive numeric membership in values=[lo, hi] (lo<=hi).
          enum:
            - EQUALS
            - IN
            - EXISTS
            - GT
            - GTE
            - LT
            - LTE
            - BETWEEN
            - NEQ
          examples:
            - EQUALS
          type: string
        value:
          description: Comparison value, required for the EQUALS operator.
          examples:
            - Banco do Brasil
          type: string
        values:
          description: Candidate values, required for the IN operator.
          items:
            type: string
          type:
            - array
            - "null"
      required:
        - field
        - operator
      type: object
    FieldPredicateResponse:
      additionalProperties: false
      properties:
        field:
          description: Transaction metadata field the predicate tests.
          examples:
            - institution
          type: string
        operator:
          description: Comparison operator. EQUALS matches a single value; NEQ is its negation (numeric when both sides parse as decimals, else case-insensitive string). IN matches any value in the values list. EXISTS asserts the field is present. GT/GTE/LT/LTE compare the field numerically against a single decimal value. BETWEEN tests inclusive numeric membership in values=[lo, hi] (lo<=hi).
          enum:
            - EQUALS
            - IN
            - EXISTS
            - GT
            - GTE
            - LT
            - LTE
            - BETWEEN
            - NEQ
          examples:
            - EQUALS
          type: string
        value:
          description: Comparison value used by the EQUALS operator.
          examples:
            - Banco do Brasil
          type: string
        values:
          description: Candidate values used by the IN operator.
          items:
            type: string
          type:
            - array
            - "null"
      required:
        - field
        - operator
      type: object
    FieldProposalResponse:
      additionalProperties: false
      properties:
        canonicalKey:
          description: Canonical field-map key the proposal targets. The closed vocabulary is the required keys (external_id, amount, currency, date) plus the optional ones (description, fee_amount, fee_currency); the advisor drops any key outside it before the proposal is returned
          enum:
            - external_id
            - amount
            - currency
            - date
            - description
            - fee_amount
            - fee_currency
          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
    FilePreviewResponse:
      additionalProperties: false
      properties:
        columns:
          description: Detected column names
          examples:
            -   - id
                - amount
                - currency
                - date
          items:
            type: string
          type:
            - array
            - "null"
        format:
          description: Detected file format; camt053 is reported when a format=xml document auto-upgrades on an ISO 20022 camt namespace
          examples:
            - csv
          type: string
        rowCount:
          description: Number of sample rows returned
          examples:
            - 5
          format: int64
          type: integer
        sampleRows:
          description: Sample data rows, one inner array per row (up to maxRows)
          items:
            items:
              type: string
            type:
              - array
              - "null"
          type:
            - array
            - "null"
      required:
        - columns
        - sampleRows
        - rowCount
        - format
      type: object
    ForceMatchRequest:
      additionalProperties: false
      properties:
        notes:
          description: Additional notes explaining the force match decision
          examples:
            - Approved by finance team after manual review
          maxLength: 1000
          minLength: 1
          type: string
        overrideReason:
          description: Reason for overriding the normal matching process
          examples:
            - BUSINESS_DECISION
          maxLength: 255
          minLength: 1
          type: string
      required:
        - overrideReason
        - notes
      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
    HistoryEntryResponse:
      additionalProperties: false
      properties:
        action:
          description: Action that was performed on the exception
          examples:
            - FORCE_MATCH
          type: string
        actorId:
          description: User who performed the action
          examples:
            - user@example.com
          type: string
        changes:
          description: JSON object describing the field-level changes made by this action
        createdAt:
          description: Timestamp of the action as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        id:
          description: Unique identifier for the history entry (UUID)
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
      required:
        - id
        - action
        - createdAt
      type: object
    HistoryResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Page of audit history entries (max 200 per page)
          items:
            $ref: "#/components/schemas/HistoryEntryResponse"
          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
    IgnoreTransactionRequest:
      additionalProperties: false
      properties:
        reason:
          description: Reason for ignoring the transaction
          examples:
            - Duplicate entry - already processed manually
          minLength: 1
          type: string
      required:
        - reason
      type: object
    IgnoreTransactionResponse:
      additionalProperties: false
      properties:
        amount:
          description: Transaction amount as a decimal string in the transaction currency (precision preserved verbatim; never a float)
          examples:
            - "1000.50"
          type: string
        contextId:
          description: Reconciliation context this transaction belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        createdAt:
          description: Creation timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          format: date-time
          type: string
        currency:
          description: ISO 4217 currency code of the amount
          examples:
            - USD
          type: string
        date:
          description: Transaction value date (RFC 3339)
          examples:
            - "2025-01-15T00:00:00Z"
          format: date-time
          type: string
        dedupeKey:
          description: "Read-only: the duplicate-key value this row was imported under, derived from the source's duplicate key declaration at import time. A source can change that declaration later, so this is the only place that says which identity THIS row carries. Prefixed v1 when the key spells out the fields it was derived from, v1h when those fields were hashed because the spelled-out key was too long to index."
          examples:
            - v1|external_id=9:TXN-12345
          type: string
        description:
          description: Free-text description carried from the source
          examples:
            - Wire transfer from ABC Corp
          type: string
        externalId:
          description: External identifier carried from the source system
          examples:
            - TXN-12345
          type: string
        extractionStatus:
          description: "Field-extraction status: PENDING (queued), COMPLETE (fields parsed), FAILED (extraction error)"
          enum:
            - PENDING
            - COMPLETE
            - FAILED
          examples:
            - COMPLETE
          type: string
        id:
          description: Unique identifier for the transaction
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        jobId:
          description: Ingestion job that produced this transaction
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        metadata:
          additionalProperties: {}
          description: "Normalized source metadata: unmapped source columns the engine projects into composite match keys and FX-conversion inputs (e.g. counterparty, bank_transaction_code, fx_rate). Arbitrary key/value, tenant-scoped to the caller's own data."
          type: object
        sourceId:
          description: Source this transaction belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        status:
          description: "Matching status: UNMATCHED (no match found), MATCHED (reconciled), IGNORED (excluded from reconciliation by an operator), PENDING_REVIEW (imported under the blank-external-id review policy and awaiting an operator decision)"
          enum:
            - UNMATCHED
            - MATCHED
            - IGNORED
            - PENDING_REVIEW
          examples:
            - UNMATCHED
          type: string
      required:
        - id
        - jobId
        - sourceId
        - contextId
        - externalId
        - dedupeKey
        - amount
        - currency
        - date
        - status
        - extractionStatus
        - createdAt
      type: object
    JobResponse:
      additionalProperties: false
      properties:
        completedAt:
          description: When the job completed (RFC 3339); null until completed
          examples:
            - "2025-01-15T10:35:00Z"
          format: date-time
          type: string
        completedWithErrors:
          description: True when the job COMPLETED but at least one row failed — distinguishes a partially-failed import from a clean one
          examples:
            - true
          type: boolean
        contextId:
          description: Reconciliation context this job belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        createdAt:
          description: Creation timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          format: date-time
          type: string
        diagnosis:
          description: Safe one-line diagnosis of anything the parser found worth reporting about the file (dialect mismatch, degraded settlement re-join, zero-detail file), the rate-policy message for policy-FAILED jobs, or a generic safe message for other FAILED jobs. Present on COMPLETED jobs too, including ones with zero failed rows; empty when there is nothing to report — internal error detail is never surfaced here
          examples:
            - file appears semicolon-delimited but the source declares comma; declare delimiter semicolon in the source dialect
          type: string
        droppedDuplicateReason:
          description: "Display-only explanation of why droppedDuplicateRows rows were kept out of the import: names the source's duplicate key as the identity that collided, says the repeats were attached as exceptions to the rows they repeated when the job flagged any (repeats of one row share one exception, so the queue holds one item per repeated row), and names the repeats that raised nothing when fewer were flagged than dropped, so the count does not read as silent data loss and the customer is sent to the configuration that decides it. Empty unless droppedDuplicateRows > 0"
          examples:
            - "Rows repeated the duplicate key this source deduplicates on and were kept out of the import. This source flags duplicates, so each repeat whose original was found was attached to that original as a duplicate exception in the exceptions queue. Repeats of the same original share one exception, so the queue holds one item per repeated row, not one per repeat. The rest found no imported row to attach to (another import of this source may still have been in progress), so no exception was raised for them and they are not in the queue: re-upload those rows once every import of this source has finished. If unexpected, review the source's duplicate key and the fields it names (a coarse or truncated mapping collapses distinct rows onto one key)."
          type: string
        droppedDuplicateRows:
          description: Number of rows kept out of the import as duplicates (rows repeating the source's duplicate key within the upload or already persisted); see flaggedDuplicateRows for how many were also raised as exceptions
          examples:
            - 60
          format: int64
          minimum: 0
          type: integer
        failedRows:
          description: Number of rows that failed parsing or normalization
          examples:
            - 5
          format: int64
          minimum: 0
          type: integer
        failureRatePercent:
          description: Percentage of rows that failed, ceiling-rounded so any failure registers as at least 1%; 0 when no rows failed
          examples:
            - 100
          format: int64
          maximum: 100
          minimum: 0
          type: integer
        fileName:
          description: Original uploaded file name
          examples:
            - transactions_2024.csv
          type: string
        flaggedDuplicateRows:
          description: "Number of dropped duplicate ROWS raised as DUPLICATE_TRANSACTION exceptions on the transaction they repeated, under the FLAG_AS_EXCEPTION duplicate policy — the default (subset of droppedDuplicateRows). Not a queue-item count: repeats of the same transaction share one exception, which carries how many times it was repeated"
          examples:
            - 15
          format: int64
          minimum: 0
          type: integer
        id:
          description: Unique identifier for the job
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        persistedRows:
          description: Number of transactions actually persisted by this job (additive diagnostics field; see also droppedDuplicateRows)
          examples:
            - 940
          format: int64
          minimum: 0
          type: integer
        reviewRows:
          description: Number of rows imported with status PENDING_REVIEW under the blank_external_id=NEEDS_REVIEW source policy — successful imports awaiting operator review, never counted as failures
          examples:
            - 9
          format: int64
          minimum: 0
          type: integer
        sourceId:
          description: Source this job ingests data into
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        startedAt:
          description: When the job started (RFC 3339); null for QUEUED jobs
          examples:
            - "2025-01-15T10:30:00Z"
          format: date-time
          type: string
        status:
          description: "Job lifecycle status: QUEUED (awaiting a worker), PROCESSING (parsing/normalizing rows), COMPLETED (finished), FAILED (aborted wholesale)"
          enum:
            - QUEUED
            - PROCESSING
            - COMPLETED
            - FAILED
          examples:
            - PROCESSING
          type: string
        totalRows:
          description: Total number of data rows detected in the file
          examples:
            - 1000
          format: int64
          minimum: 0
          type: integer
      required:
        - id
        - contextId
        - sourceId
        - status
        - persistedRows
        - droppedDuplicateRows
        - flaggedDuplicateRows
        - reviewRows
        - completedWithErrors
        - failureRatePercent
        - createdAt
      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 — declaring it string or date is refused by the server-side submission gate, which the schema enum does not replace"
          enum:
            - string
            - decimal
            - date
          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"
          enum:
            - string
            - decimal
            - 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
    ListAdjustmentsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Page of recorded adjustments
          items:
            $ref: "#/components/schemas/AdjustmentResponse"
          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
    ListArchivesResponse:
      additionalProperties: false
      properties:
        hasMore:
          description: True when more archives exist beyond this page
          examples:
            - true
          type: boolean
        items:
          description: Completed audit log archives for the current page
          items:
            $ref: "#/components/schemas/ArchiveMetadataResponse"
          maxItems: 200
          type:
            - array
            - "null"
        limit:
          description: Page size applied to this response (offset-based pagination)
          examples:
            - 20
          format: int64
          maximum: 200
          minimum: 1
          type: integer
      required:
        - items
        - limit
        - hasMore
      type: object
    ListAuditLogsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Audit log entries for the current page
          items:
            $ref: "#/components/schemas/AuditLogResponse"
          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
    ListCommentsResponse:
      additionalProperties: false
      properties:
        items:
          description: Comments for the exception, ordered by creation time (oldest first)
          items:
            $ref: "#/components/schemas/CommentResponse"
          type:
            - array
            - "null"
      required:
        - items
      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
    ListContextsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/ReconciliationContextResponse"
          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
        total:
          examples:
            - 42
          format: int64
          type: integer
      required:
        - items
        - total
        - limit
        - hasMore
      type: object
    ListDisputesResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Page of disputes (max 200 per page)
          items:
            $ref: "#/components/schemas/DisputeResponse"
          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
    ListExceptionsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Page of exceptions (max 200 per page)
          items:
            $ref: "#/components/schemas/ExceptionResponse"
          maxItems: 200
          type:
            - array
            - "null"
        limit:
          examples:
            - 20
          format: int64
          maximum: 200
          minimum: 1
          type: integer
        nextCursor:
          examples:
            - eyJpZCI6IjEyMyJ9
          type: string
        openTotal:
          description: Non-terminal exceptions (OPEN, ASSIGNED, PENDING_RESOLUTION) matching the filter
          examples:
            - 412
          format: int64
          type: integer
        overdueTotal:
          description: Non-terminal exceptions past their due date matching the filter
          examples:
            - 38
          format: int64
          type: integer
        prevCursor:
          examples:
            - eyJpZCI6IjEyMiJ9
          type: string
        resolvedTotal:
          description: Resolved exceptions matching the filter
          examples:
            - 118
          format: int64
          type: integer
        total:
          description: Total exceptions matching the filter (full set, not the page)
          examples:
            - 530
          format: int64
          type: integer
      required:
        - items
        - total
        - openTotal
        - overdueTotal
        - resolvedTotal
        - limit
        - hasMore
      type: object
    ListFeeRulesResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Fee rules in the current page.
          items:
            $ref: "#/components/schemas/FeeRuleResponse"
          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
    ListFeeSchedulesResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Fee schedules in the current page.
          items:
            $ref: "#/components/schemas/FeeScheduleResponse"
          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
    ListJobsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Ingestion jobs on this page
          items:
            $ref: "#/components/schemas/JobResponse"
          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
    ListLayoutTemplatesResponse:
      additionalProperties: false
      properties:
        items:
          description: Active operator layout templates
          items:
            $ref: "#/components/schemas/LayoutTemplateResponse"
          type:
            - array
            - "null"
      required:
        - items
      type: object
    ListMatchGroupsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Page of match groups
          items:
            $ref: "#/components/schemas/MatchGroupResponse"
          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
    ListMatchRulesResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/MatchRuleResponse"
          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
    ListMatchRunsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Page of match runs
          items:
            $ref: "#/components/schemas/MatchRunResponse"
          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
    ListMatchedReportResponse:
      additionalProperties: false
      properties:
        items:
          description: Matched transactions in the current page.
          items:
            $ref: "#/components/schemas/MatchedItemResponse"
          type:
            - array
            - "null"
        pagination:
          $ref: "#/components/schemas/CursorPagination"
      required:
        - items
        - pagination
      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
    ListSourcesResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          items:
            $ref: "#/components/schemas/SourceWithFieldMapStatusResponse"
          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
    ListTransactionsResponse:
      additionalProperties: false
      properties:
        hasMore:
          examples:
            - true
          type: boolean
        items:
          description: Transactions on this page
          items:
            $ref: "#/components/schemas/TransactionResponse"
          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
    ListUnmatchedReportResponse:
      additionalProperties: false
      properties:
        items:
          description: Unmatched transactions in the current page.
          items:
            $ref: "#/components/schemas/UnmatchedItemResponse"
          type:
            - array
            - "null"
        pagination:
          $ref: "#/components/schemas/CursorPagination"
      required:
        - items
        - pagination
      type: object
    ListVarianceReportResponse:
      additionalProperties: false
      properties:
        items:
          description: Variance report rows in the current page.
          items:
            $ref: "#/components/schemas/VarianceReportRowResponse"
          type:
            - array
            - "null"
        pagination:
          $ref: "#/components/schemas/CursorPagination"
        unattributedAdjustments:
          description: Per-currency totals of the window's recorded adjustments that no row includes, sorted by currency. They sit outside items and must not be added to any row; the list is identical on every page of one query, and empty when there are none.
          items:
            $ref: "#/components/schemas/UnattributedAdjustmentResponse"
          type: array
      required:
        - items
        - pagination
        - unattributedAdjustments
      type: object
    ManualMatchResponse:
      additionalProperties: false
      properties:
        matchGroup:
          $ref: "#/components/schemas/MatchGroupResponse"
          description: The match group created by linking the supplied transactions
      required:
        - matchGroup
      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
    MatchGroupResponse:
      additionalProperties: false
      properties:
        confidence:
          description: Match confidence score from 0 (lowest) to 100 (exact); manual matches are 100
          examples:
            - 85
          format: int64
          maximum: 100
          minimum: 0
          type: integer
        confirmedAt:
          description: When the group was confirmed (RFC 3339); present only once confirmed
          examples:
            - "2025-01-15T10:35:00Z"
          type: string
        contextId:
          description: Reconciliation context ID this group belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        createdAt:
          description: Creation timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        id:
          description: Unique identifier for the group
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        items:
          description: Transaction allocations that make up this match group
          items:
            $ref: "#/components/schemas/MatchItemResponse"
          maxItems: 500
          type:
            - array
            - "null"
        reasonCodes:
          description: Rationale reason codes attached to this group's member transactions (e.g. FX_RATE_VARIANCE, FEE_VARIANCE, AGED_BREAK, OVER_SETTLED), resolved by joining member exceptions. Absent for a clean match with no recorded rationale
          examples:
            -   - FX_RATE_VARIANCE
          items:
            type: string
          maxItems: 32
          type:
            - array
            - "null"
        rejectedReason:
          description: Reason the group was rejected; present only when the status is REJECTED
          examples:
            - amounts do not match within tolerance
          type: string
        ruleId:
          description: Identifier of the rule used for matching; null for manual matches
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        runId:
          description: Identifier of the match run that created this group
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        status:
          description: "Current status of the group: PROPOSED (awaiting review), CONFIRMED (accepted), REJECTED (a proposed group discarded before confirmation), or REVOKED (a confirmed group whose confirmation was later undone by an unmatch; the original confirmation timestamp is kept for audit)"
          enum:
            - PROPOSED
            - CONFIRMED
            - REJECTED
            - REVOKED
          examples:
            - PROPOSED
          type: string
        updatedAt:
          description: Last update timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - contextId
        - runId
        - confidence
        - status
        - items
        - createdAt
        - updatedAt
      type: object
    MatchItemResponse:
      additionalProperties: false
      properties:
        allocatedAmount:
          description: Amount allocated to this match, as a decimal string in the allocated currency's minor-unit precision
          examples:
            - "1000.00"
          type: string
        allocatedCurrency:
          description: ISO 4217 currency code of the allocated amount
          examples:
            - USD
          type: string
        allowPartial:
          description: Whether partial allocation of the transaction is permitted
          examples:
            - false
          type: boolean
        createdAt:
          description: Creation timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        expectedAmount:
          description: Amount expected for a full match, as a decimal string
          examples:
            - "1000.00"
          type: string
        id:
          description: Unique identifier for the item
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        matchGroupId:
          description: Identifier of the match group this item belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        side:
          description: "Reconciliation side of the item's source: LEFT or RIGHT. Resolved from the transaction's source; absent when the source side could not be resolved"
          enum:
            - LEFT
            - RIGHT
          examples:
            - LEFT
          type: string
        sourceId:
          description: Identifier of the reconciliation source the item's transaction belongs to; absent when unresolved
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        sourceName:
          description: Human-readable name of the reconciliation source; absent when unresolved
          examples:
            - Bank statement
          type: string
        transactionId:
          description: Identifier of the transaction being matched
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        updatedAt:
          description: Last update timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - matchGroupId
        - transactionId
        - allocatedAmount
        - allocatedCurrency
        - expectedAmount
        - allowPartial
        - createdAt
        - updatedAt
      type: object
    MatchRateStatsResponse:
      additionalProperties: false
      properties:
        matchRate:
          description: Percentage of transactions matched by count (0-100).
          examples:
            - 94.4
          format: double
          type: number
        matchRateAmount:
          description: Percentage of transaction value matched by monetary amount (0-100).
          examples:
            - 94.4
          format: double
          type: number
        matchedCount:
          description: Number of matched transactions.
          examples:
            - 11800
          format: int64
          type: integer
        totalCount:
          description: Total number of transactions considered for the match rate.
          examples:
            - 12500
          format: int64
          type: integer
        unmatchedCount:
          description: Number of unmatched transactions.
          examples:
            - 700
          format: int64
          type: integer
      required:
        - matchRate
        - matchRateAmount
        - totalCount
        - matchedCount
        - unmatchedCount
      type: object
    MatchRuleResponse:
      additionalProperties: false
      properties:
        config:
          additionalProperties: {}
          description: Rule-specific configuration object (matched fields and tolerance/lag parameters).
          type: object
        contextId:
          description: Identifier of the context this rule 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
        id:
          description: Unique identifier of the rule.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        priority:
          description: Execution priority; lower numbers run first.
          examples:
            - 1
          format: int64
          maximum: 1000
          minimum: 1
          type: integer
        type:
          description: Matching strategy. EXACT requires identical field values; TOLERANCE allows configured numeric slack; DATE_LAG allows a configured date offset between sides; FUZZY matches on normalized/similarity-scored references and always proposes for review.
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
            - FUZZY
          examples:
            - EXACT
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - contextId
        - priority
        - type
        - config
        - createdAt
        - updatedAt
      type: object
    MatchRunResponse:
      additionalProperties: false
      properties:
        completedAt:
          description: When the run completed (RFC 3339 timestamp); absent until the run finishes
          examples:
            - "2025-01-15T10:35:00Z"
          type: string
        contextId:
          description: Reconciliation context ID this run belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        createdAt:
          description: Creation timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        failureReason:
          description: Failure reason; present only when the run status is FAILED
          examples:
            - no matching rules found
          type: string
        id:
          description: Unique identifier for the run
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        mode:
          description: "Execution mode: DRY_RUN evaluates rules without committing matches; COMMIT persists matches"
          enum:
            - DRY_RUN
            - COMMIT
          examples:
            - DRY_RUN
          type: string
        ruleStats:
          description: Structured per-rule matched group counts frozen at run completion. Every rule configured at run time appears, including zero-match rules, and the matched counts sum to the run's matches stat. Absent on runs completed before the keys were introduced
          items:
            $ref: "#/components/schemas/MatchRunRuleStatResponse"
          type:
            - array
            - "null"
        startedAt:
          description: When the run started (RFC 3339 timestamp)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        stats:
          additionalProperties:
            format: int64
            type: integer
          description: Aggregate run statistics as an open key-value map; consumers must tolerate unknown keys and treat a missing key as unknown rather than zero. Known keys include matches, candidates_left, candidates_right, unmatched_left, unmatched_right, unmatched_external, auto_matched_left, auto_matched_right, pending_review_left, pending_review_right, proposed_left, proposed_right, exceptions_raised (newly created), exceptions_updated (re-touched), plus per-rule families rule_matched:<ruleID> and rule_meta:<ruleID>:<TYPE>. A run recovered after an interruption reports the exception rows its earlier attempt created under exceptions_updated, not exceptions_raised
          type: object
        status:
          description: "Current status of the run: QUEUED (async submit, awaiting worker pickup), PROCESSING (in flight), FINALIZING (a transient finishing-up state — a poll MAY briefly observe it between PROCESSING and COMPLETED, and it is also observable while a run is recovered after a crash; treat it as in-flight, not terminal), COMPLETED (finished), or FAILED (errored). An async run in flight when its pod stops goes back from PROCESSING to QUEUED and is picked up again with a new startedAt"
          enum:
            - QUEUED
            - PROCESSING
            - FINALIZING
            - COMPLETED
            - FAILED
          examples:
            - COMPLETED
          type: string
        updatedAt:
          description: Last update timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - contextId
        - mode
        - status
        - startedAt
        - createdAt
        - updatedAt
      type: object
    MatchRunRuleStatResponse:
      additionalProperties: false
      properties:
        matched:
          description: Match groups this rule produced in this run; zero means the rule matched nothing, and counts across all rules sum to the run's matches stat
          examples:
            - 42
          format: int64
          type: integer
        priority:
          description: Rule priority at run time (lower runs first)
          examples:
            - 1
          format: int64
          type: integer
        ruleId:
          description: Identifier of the match rule, frozen at run completion
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        type:
          description: "Rule type at run time: EXACT (strict equality), TOLERANCE (within an amount band), DATE_LAG (allowing a settlement-date offset), or FUZZY (normalized/similarity-scored references, always proposes). Absent when the run recorded a match count for the rule without its metadata sibling"
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
            - FUZZY
          examples:
            - EXACT
          type: string
      required:
        - ruleId
        - priority
        - matched
      type: object
    MatchedItemResponse:
      additionalProperties: false
      properties:
        amount:
          description: Transaction amount as a decimal string in the transaction's currency.
          examples:
            - "1250.50"
          type: string
        currency:
          description: ISO 4217 currency code of the transaction amount.
          examples:
            - USD
          type: string
        date:
          description: Transaction value date (RFC 3339 timestamp, UTC).
          examples:
            - "2025-01-15T10:30:00Z"
          format: date-time
          type: string
        matchGroupId:
          description: Identifier of the match group the transaction belongs to (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        sourceId:
          description: Identifier of the source the transaction came from (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        transactionId:
          description: Identifier of the matched transaction (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
      required:
        - transactionId
        - matchGroupId
        - sourceId
        - amount
        - currency
        - date
      type: object
    MatcherDashboardMetricsResponse:
      additionalProperties: false
      properties:
        breakdowns:
          $ref: "#/components/schemas/BreakdownMetricsResponse"
          description: Categorical aggregations of exceptions and matches.
        summary:
          $ref: "#/components/schemas/SummaryMetricsResponse"
          description: Executive summary metrics.
        trends:
          $ref: "#/components/schemas/TrendMetricsResponse"
          description: Time-series trend data across the window.
        updatedAt:
          description: Timestamp when these metrics were computed (RFC 3339, UTC).
          examples:
            - "2025-01-15T10:30:00Z"
          format: date-time
          type: string
      required:
        - summary
        - trends
        - breakdowns
        - updatedAt
      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
    OpenDisputeRequest:
      additionalProperties: false
      properties:
        category:
          description: Category of the dispute
          examples:
            - AMOUNT_MISMATCH
          maxLength: 255
          minLength: 1
          type: string
        description:
          description: Detailed description of the dispute
          examples:
            - Transaction amount differs from invoice
          maxLength: 5000
          minLength: 1
          type: string
      required:
        - category
        - description
      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: "Total owed on the item's identity: the face of the obligation it opened on plus every later obligation with the same identity, 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), AGED (exceeded its aging threshold while still open), or WITHDRAWN (the confirmed match that opened it was un-matched, so the obligation was taken back with it)"
          enum:
            - OPEN
            - PARTIALLY_CLEARED
            - CLEARED
            - AGED
            - WITHDRAWN
          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
    ProcessCallbackRequest:
      additionalProperties: false
      properties:
        assignee:
          description: Assignee identifier (required when status is ASSIGNED)
          examples:
            - user@example.com
          type: string
        callbackType:
          description: Type of callback (e.g. status_update, assignment)
          examples:
            - status_update
          type: string
        dueAt:
          description: Due date for resolution as an RFC 3339 timestamp
          examples:
            - "2025-01-20T10:30:00Z"
          type:
            - string
            - "null"
        externalIssueId:
          description: Issue ID in the external system
          examples:
            - RECON-1234
          minLength: 1
          type: string
        externalSystem:
          description: External system identifier (e.g. JIRA, SERVICENOW, WEBHOOK)
          examples:
            - JIRA
          minLength: 1
          type: string
        payload:
          additionalProperties: {}
          description: Arbitrary payload from the external system
          type: object
        resolutionNotes:
          description: Optional resolution notes
          examples:
            - Resolved by external agent
          type: string
        status:
          description: Target status for the exception (e.g. ASSIGNED, RESOLVED)
          examples:
            - RESOLVED
          minLength: 1
          type: string
        updatedAt:
          description: External system timestamp as an RFC 3339 timestamp
          examples:
            - "2025-01-15T10:30:00Z"
          type:
            - string
            - "null"
      required:
        - callbackType
        - externalSystem
        - externalIssueId
        - status
        - resolutionNotes
        - assignee
        - dueAt
        - updatedAt
        - payload
      type: object
    ProcessCallbackResponse:
      additionalProperties: false
      properties:
        status:
          description: Processing status of the callback (the handler always returns "accepted" on success)
          examples:
            - accepted
          type: string
      required:
        - status
      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
    RESTConnectionRequest:
      additionalProperties: false
      properties:
        apiKey:
          description: Stripe restricted API key
          maxLength: 512
          type: string
        baseURL:
          description: Optional per-connection API base URL (http/https); when omitted the deployment default for the connector type is used
          examples:
            - https://sandbox.provider.example
          format: uri
          maxLength: 2048
          type: string
        clientCert:
          description: PEM-encoded Pix client certificate
          maxLength: 8192
          type: string
        clientID:
          description: Pix OAuth2 client id
          maxLength: 512
          type: string
        clientKey:
          description: PEM-encoded Pix client private key
          maxLength: 8192
          type: string
        clientSecret:
          description: Pix OAuth2 client secret
          maxLength: 512
          type: string
        configName:
          description: Unique connection config name (tenant-scoped)
          examples:
            - pagbank-prod
          maxLength: 255
          minLength: 1
          type: string
        connectorType:
          description: REST connector type this connection serves
          enum:
            - PAGBANK
            - STRIPE
            - PIX_BCB
          examples:
            - PAGBANK
          minLength: 1
          type: string
        ediToken:
          description: PagBank EDI token
          maxLength: 512
          type: string
        establishmentID:
          description: PagBank establishment id
          maxLength: 512
          type: string
      required:
        - configName
        - connectorType
      type: object
    ReconciliationContextResponse:
      additionalProperties: false
      properties:
        agedBreakCalendar:
          description: Business-day calendar the aging threshold is measured against. Absent/empty means raw calendar days.
          examples:
            - BR_ANBIMA
          type: string
        agedBreakThresholdDays:
          description: Open-item aging SLA in business days. An open-item residual older than this surfaces as an AGED_BREAK exception. Absent when aging is disabled for the context.
          examples:
            - 30
          format: int64
          type: integer
        autoMatchOnUpload:
          description: When true, a match run is triggered automatically after a file upload completes.
          examples:
            - false
          type: boolean
        createdAt:
          description: Creation timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        feeNormalization:
          description: Fee normalization mode. NET compares amounts after fees are deducted; GROSS compares amounts before fees.
          enum:
            - NET
            - GROSS
          examples:
            - NET
          type: string
        feeToleranceAbs:
          description: Absolute fee tolerance as a decimal string in the context currency.
          examples:
            - "0.50"
          type: string
        feeTolerancePct:
          description: Percentage fee tolerance as a decimal string (0.01 means 0.01%).
          examples:
            - "0.01"
          type: string
        id:
          description: Unique identifier of the context.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        interval:
          description: Execution interval label for the context (e.g. daily, weekly).
          examples:
            - daily
          type: string
        name:
          description: Human-readable name of the reconciliation context.
          examples:
            - Bank Reconciliation Q1
          type: string
        signConvention:
          description: "How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles. In 1:N contexts only payments of the declared sign are allocated to an invoice, and in N:M contexts a short-paid invoice keeps an open balance only when it is positive under SAME, or when the rule's sign mode is opposite under OPPOSITE; any other short payment stays unmatched; a carried open balance settles on a payment of the declared sign or on a reversal from the invoice's own side, and a row from an archived source stays unmatched. It cannot change once the context has carried a partial balance, or while a match run is in progress."
          enum:
            - SAME
            - OPPOSITE
          examples:
            - SAME
          type: string
        status:
          description: Lifecycle status. DRAFT is being configured; ACTIVE runs; PAUSED is suspended; ARCHIVED is retired.
          enum:
            - DRAFT
            - ACTIVE
            - PAUSED
            - ARCHIVED
          examples:
            - ACTIVE
          type: string
        tenantId:
          description: Identifier of the tenant that owns the context.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        type:
          description: Reconciliation topology. 1:1 matches one left transaction to one right transaction; 1:N matches one transaction against many on the other side; N:M matches groups on both sides.
          enum:
            - "1:1"
            - 1:N
            - N:M
          examples:
            - "1:1"
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - tenantId
        - name
        - type
        - interval
        - status
        - feeToleranceAbs
        - feeTolerancePct
        - autoMatchOnUpload
        - signConvention
        - createdAt
        - updatedAt
      type: object
    ReconciliationSourceResponse:
      additionalProperties: false
      properties:
        archivedAt:
          description: RFC 3339 timestamp when the source was archived; absent when the source is live.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        config:
          additionalProperties: {}
          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
          properties:
            blank_external_id:
              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
              enum:
                - REJECT
                - NEEDS_REVIEW
              type: string
            camt053:
              additionalProperties: false
              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
              properties:
                date_basis:
                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
                  enum:
                    - booking
                    - valuation
                  type: string
                external_id_source:
                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
                  enum:
                    - ntry_ref
                    - end_to_end_id
                    - tx_id
                  type: string
              type: object
            dialect:
              additionalProperties: false
              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
              properties:
                date_style:
                  enum:
                    - iso
                    - iso_offset
                    - dmy
                    - mdy
                  type: string
                decimal_style:
                  description: dot is 1234.56, comma is 1.234,56.
                  enum:
                    - dot
                    - comma
                  type: string
                delimiter:
                  enum:
                    - comma
                    - semicolon
                    - tab
                    - pipe
                  type: string
                encoding:
                  enum:
                    - utf-8
                    - utf-8-sig
                    - cp1252
                    - iso-8859-1
                  type: string
              type: object
            duplicate_key:
              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
              items:
                enum:
                  - external_id
                  - amount
                  - currency
                  - date
                  - description
                  - fee_amount
                  - fee_currency
                type: string
              minItems: 1
              type: array
              uniqueItems: true
            duplicate_key_changed_at:
              description: SERVER-OWNED. The moment duplicate-key detection last changed meaning on this source, either because duplicate_key was edited or because the field map remapped the column a declared component reads. Rows imported before it keep the key they were deduplicated under. A value sent by a client is discarded.
              format: date-time
              readOnly: true
              type: string
            duplicate_policy:
              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
              enum:
                - FLAG_AS_EXCEPTION
                - KEEP_FIRST
                - REJECT
              type: string
            fail_on_error_rate_percent:
              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
              maximum: 99
              minimum: 1
              type: integer
          type: object
        contextId:
          description: Identifier of the context this source 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
        id:
          description: Unique identifier of the source.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        name:
          description: Human-readable name of the source.
          examples:
            - Primary Bank Account
          type: string
        side:
          description: Matching side this source feeds. LEFT and RIGHT are the two sides reconciled against each other.
          enum:
            - LEFT
            - RIGHT
          examples:
            - LEFT
          type: string
        type:
          description: Origin of the source data. LEDGER is the internal ledger; BANK is a bank statement feed; GATEWAY is a payment gateway; CUSTOM is a bespoke feed; FETCHER is a discovery-engine pull.
          enum:
            - LEDGER
            - BANK
            - GATEWAY
            - CUSTOM
            - FETCHER
          examples:
            - BANK
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - contextId
        - name
        - type
        - side
        - config
        - createdAt
        - updatedAt
      type: object
    RefreshDiscoveryResponse:
      additionalProperties: false
      properties:
        connectionsSynced:
          description: Number of connections synchronized during the refresh
          examples:
            - 3
          format: int64
          type: integer
      required:
        - connectionsSynced
      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
    ReorderRequest:
      additionalProperties: false
      properties:
        ruleIds:
          description: Ordered list of match rule UUIDs. The new priority of each rule is its position in this list.
          items:
            type: string
          maxItems: 100
          minItems: 1
          type:
            - array
            - "null"
      required:
        - ruleIds
      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
    RuleMatchCountDTO:
      additionalProperties: false
      properties:
        count:
          description: Number of matches attributed to this rule.
          examples:
            - 1250
          format: int64
          type: integer
        id:
          description: Identifier of the match rule (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        name:
          description: Human-readable name of the match rule.
          examples:
            - Exact Amount Match
          type: string
      required:
        - id
        - name
        - count
      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). FUZZY is excluded on purpose: a fuzzy rule only ever proposes graded-confidence links a human must review, so an operator configures one deliberately rather than accepting it from a suggestion"
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
          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)"
          enum:
            - PENDING_REVIEW
            - APPROVED
            - REJECTED
          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
    RunMatchRequest:
      additionalProperties: false
      properties:
        async:
          description: "Submit asynchronously: when true the run is queued (status QUEUED) and executed by the worker; when false/omitted the run executes in-request and the response carries the completed run (terminal status). Both paths return HTTP 202; distinguish by the response status. Poll GET /v1/matching/runs/{runId} for async progress."
          examples:
            - false
          type: boolean
        mode:
          description: Execution mode
          enum:
            - DRY_RUN
            - COMMIT
          examples:
            - DRY_RUN
          type: string
      required:
        - mode
      type: object
    RunMatchResponse:
      additionalProperties: false
      properties:
        runId:
          description: Identifier of the match run that was triggered
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        status:
          description: "Status of the run at acceptance: QUEUED (async submit, awaiting worker pickup), COMPLETED (finished synchronously), or FAILED (errored synchronously). A synchronous run is already terminal; an async run is QUEUED. Poll GET /v1/matching/runs/{runId} for async progress (PROCESSING/FINALIZING/COMPLETED)"
          enum:
            - QUEUED
            - COMPLETED
            - FAILED
          examples:
            - COMPLETED
          type: string
      required:
        - runId
        - status
      type: object
    SLAStatsResponse:
      additionalProperties: false
      properties:
        averageResolutionMs:
          description: Average time to resolve an exception, in milliseconds.
          examples:
            - 3600000
          format: int64
          type: integer
        pendingOverdue:
          description: Number of open exceptions that have breached their SLA deadline.
          examples:
            - 2
          format: int64
          type: integer
        pendingWithinSLA:
          description: Number of open exceptions still within their SLA deadline.
          examples:
            - 2
          format: int64
          type: integer
        resolvedLate:
          description: Number of exceptions resolved after their SLA deadline.
          examples:
            - 3
          format: int64
          type: integer
        resolvedOnTime:
          description: Number of exceptions resolved within their SLA deadline.
          examples:
            - 35
          format: int64
          type: integer
        slaComplianceRate:
          description: Percentage of exceptions meeting their SLA (0-100).
          examples:
            - 83.3
          format: double
          type: number
        totalExceptions:
          description: Total number of exceptions in scope for SLA evaluation.
          examples:
            - 42
          format: int64
          type: integer
      required:
        - totalExceptions
        - resolvedOnTime
        - resolvedLate
        - pendingWithinSLA
        - pendingOverdue
        - slaComplianceRate
        - averageResolutionMs
      type: object
    ScheduleResponse:
      additionalProperties: false
      properties:
        contextId:
          description: Identifier of the context this schedule 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
        cronExpression:
          description: Cron expression (5-field) defining when the reconciliation runs.
          examples:
            - 0 0 * * *
          type: string
        enabled:
          description: Whether the schedule is active.
          examples:
            - true
          type: boolean
        id:
          description: Unique identifier of the schedule.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        lastRunAt:
          description: Timestamp of the last successful run in RFC 3339 format; omitted if it has never run.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        nextRunAt:
          description: Timestamp of the next scheduled run in RFC 3339 format; omitted when disabled.
          examples:
            - "2025-01-16T00:00:00Z"
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - id
        - contextId
        - cronExpression
        - enabled
        - createdAt
        - updatedAt
      type: object
    SchemaColumnResponse:
      additionalProperties: false
      properties:
        name:
          description: Column name
          examples:
            - amount
          type: string
        nullable:
          description: Historical nullability flag; omitted when unknown
          type: boolean
        type:
          description: Historical column data type; omitted when unknown
          examples:
            - numeric
          type: string
      required:
        - name
      type: object
    SchemaGenerationResponse:
      additionalProperties: false
      properties:
        archivedAt:
          description: When this generation stopped being the live schema map
          examples:
            - "2026-07-15T12:30:00Z"
          format: date-time
          type: string
        fieldReport:
          description: "How this retired generation's field lists were obtained, read off its own rows: ENUMERATED from the source's own catalog, exhaustively for the credential that read it, so this generation's column sets are a statement about the source; SAMPLED from a sample of the source's data (MongoDB reads the union of top-level keys over $sample-d documents), so it may name a field the source no longer held, because nothing observed a removal — how such a field list built up while this generation was live, and what closed the generation, is stated in full in this operation's description. Present only when every table of this generation records the same kind: absent when they disagree, for every generation retired before the fact was recorded per row, and when the probe that installed a table of it could not show which connector produced its snapshot. It is never derived from the connection's current databaseType: that field is editable and a generation's provenance is not"
          enum:
            - ENUMERATED
            - SAMPLED
          examples:
            - SAMPLED
          type: string
        retirementCause:
          description: What was observed of this whole generation when it was retired, when every table in it agrees; absent when one install retired different tables for different observed reasons, in which case each table carries its own. Values carry the same meanings as on a table, and none of them asserts that the source removed anything
          enum:
            - ABSENT_FROM_CATALOG
            - COLUMN_SET_SUPERSEDED
            - CONNECTION_RETIRED
            - UNKNOWN_LEGACY
          examples:
            - ABSENT_FROM_CATALOG
          type: string
        tables:
          description: The tables and columns this generation of the map asserted
          items:
            $ref: "#/components/schemas/SchemaTableResponse"
          type:
            - array
            - "null"
      required:
        - archivedAt
        - tables
      type: object
    SchemaTableResponse:
      additionalProperties: false
      properties:
        columns:
          description: "Columns discovered for the table. WHAT THIS LIST IS A STATEMENT ABOUT DEPENDS ON HOW THE CONNECTOR OBTAINED IT — see fieldReport on the map, or on the generation, that carries this table. WHERE THE FIELD LISTS ARE ENUMERATED from the source's own catalog, these are the columns the latest probe asserted for the credential that read it. WHERE THEY ARE SAMPLED from the source's data instead, a field listed here may appear in no document the source currently holds: it carries no marker saying so and stays extractable, deliberately, because nothing observed its removal. How a sampled connector's field lists build up, and what ends that, is stated in full in this operation's description — read it before authoring a field map against these columns"
          items:
            $ref: "#/components/schemas/SchemaColumnResponse"
          type:
            - array
            - "null"
        columnsNarrowed:
          description: "The source now reports FEWER columns for this table than the read before did: the columns shown were confirmed by the latest probe, and at least one column it used to report is no longer among them. The table stays extractable from the narrower set; a field map projecting a column that stopped being reported will fail at extraction. It says nothing about WHY the set narrowed — a narrowed grant and a dropped column are the same answer from a catalog"
          type: boolean
        columnsStale:
          description: "The last probe named this table without confirming its columns, so the column list is the last CONFIRMED one and may no longer match the source. The table is still extractable from it; a field map authored against it may silently stop matching. ABSENT DOES NOT MEAN THE WHOLE LIST WAS CONFIRMED BY THE LATEST PROBE: it means that probe reported columns for this table, which confirms the list only where the field lists are ENUMERATED from a catalog. Where they are SAMPLED from the source's data a draw confirms only the fields it showed, and the rest of the list may include fields the latest draw did not show — see columns, and this operation's description, which states in full how such a list builds up and what ends it"
          type: boolean
        notYetExtractableReason:
          description: Why this table cannot be extracted from yet; absent when it can. COLUMNS_NOT_ENUMERATED means the source named the table but no columns for it, which is indistinguishable between a source with no columns to give and columns the connection's credential cannot read
          enum:
            - COLUMNS_NOT_ENUMERATED
          examples:
            - COLUMNS_NOT_ENUMERATED
          type: string
        retirementCause:
          description: What was observed when this table's row stopped being the live truth; absent on a live row. ABSENT_FROM_CATALOG means the source's catalog no longer listed the table, which does NOT distinguish a dropped table from one this connection's credential can no longer see. COLUMN_SET_SUPERSEDED means the catalog still listed it with a different non-empty column set, the same ambiguity one level down; it is recorded only for a report that ENUMERATED the source's catalog, because a report whose field list was sampled from the source's data retires no column set when a draw differs — so a sampled table reaches this cause when its connection is retyped to a connector that enumerates and the catalog list supersedes the accumulated union. CONNECTION_RETIRED means an operator retired the connection, the one cause that is genuinely known. UNKNOWN_LEGACY means the row was archived by an earlier release that recorded no cause
          enum:
            - ABSENT_FROM_CATALOG
            - COLUMN_SET_SUPERSEDED
            - CONNECTION_RETIRED
            - UNKNOWN_LEGACY
          examples:
            - ABSENT_FROM_CATALOG
          type: string
        tableName:
          description: Name of the discovered table
          examples:
            - transactions
          type: string
      required:
        - tableName
        - columns
      type: object
    SearchTransactionsResponse:
      additionalProperties: false
      properties:
        items:
          description: Matching transactions on this page
          items:
            $ref: "#/components/schemas/TransactionResponse"
          type:
            - array
            - "null"
        limit:
          description: Maximum results per page
          examples:
            - 20
          format: int64
          type: integer
        offset:
          description: Current offset into the result set
          examples:
            - 0
          format: int64
          type: integer
        total:
          description: Total number of matching transactions across all pages
          examples:
            - 42
          format: int64
          type: integer
      required:
        - items
        - total
        - limit
        - offset
      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: Status of the latest match run.
          examples:
            - COMPLETED
          type: string
      required:
        - id
        - status
      type:
        - object
        - "null"
    SetupProgressMatchRulesResponse:
      additionalProperties: false
      properties:
        total:
          description: Total number of match rules in the context.
          examples:
            - 3
          format: int64
          type: integer
      required:
        - total
      type: object
    SetupProgressNextResponse:
      additionalProperties: false
      properties:
        forSource:
          $ref: "#/components/schemas/SetupProgressSourceRef"
          description: Source the action targets; set only for the source-mapping action, naming the unmapped source.
        method:
          description: HTTP method of the create endpoint.
          examples:
            - POST
          type: string
        operationId:
          description: OpenAPI operationId of the create endpoint to call.
          examples:
            - createSource
          type: string
        path:
          description: Path template of the create endpoint.
          examples:
            - /v1/contexts/{contextId}/sources
          type: string
        requiredFields:
          description: Names of the fields the create request requires; the caller supplies the values.
          examples:
            -   - name
                - type
                - side
          items:
            type: string
          type:
            - array
            - "null"
        requirementId:
          description: Public activation-requirement identifier this action satisfies.
          enum:
            - context.activation.requirement.left-source
            - context.activation.requirement.right-source
            - context.activation.requirement.source-mapping
            - context.activation.requirement.match-rule
            - context.activation.requirement.fee-rule
          examples:
            - context.activation.requirement.left-source
          type: string
      required:
        - requirementId
        - operationId
        - method
        - path
        - requiredFields
      type:
        - object
        - "null"
    SetupProgressReadinessResponse:
      additionalProperties: false
      properties:
        missing:
          description: Stable identifiers of missing activation requirements; empty when ready.
          examples:
            -   - context.activation.requirement.left-source
                - context.activation.requirement.match-rule
          items:
            enum:
              - context.activation.requirement.left-source
              - context.activation.requirement.right-source
              - context.activation.requirement.source-mapping
              - context.activation.requirement.match-rule
              - context.activation.requirement.fee-rule
              - context.activation.requirement.unknown
            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.
        next:
          $ref: "#/components/schemas/SetupProgressNextResponse"
          description: Deterministic next setup action derived from readiness; null when the context is ready.
        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
        - next
      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
    SetupProgressSourceRef:
      additionalProperties: false
      properties:
        id:
          description: Identifier of the referenced source.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        name:
          description: Human-readable name of the referenced source.
          examples:
            - Bank statement
          type: string
      required:
        - id
        - name
      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
    SimulateFeeItem:
      additionalProperties: false
      properties:
        baseUsed:
          description: Base amount this item's fee was computed from, as a decimal string.
          examples:
            - "100.00"
          type: string
        fee:
          description: Fee charged by this item, as a decimal string.
          examples:
            - "1.50"
          type: string
        name:
          description: Name of the fee item.
          examples:
            - interchange
          type: string
      required:
        - name
        - fee
        - baseUsed
      type: object
    SimulateFeeRequest:
      additionalProperties: false
      properties:
        currency:
          description: ISO 4217 currency code of the gross amount.
          examples:
            - USD
          type: string
        grossAmount:
          description: Gross amount to simulate fees against, as a decimal string in the given currency.
          examples:
            - "100.00"
          type: string
      required:
        - grossAmount
        - currency
      type: object
    SimulateFeeResponse:
      additionalProperties: false
      properties:
        currency:
          description: ISO 4217 currency code of the simulated amounts.
          examples:
            - USD
          type: string
        grossAmount:
          description: Gross amount that fees were simulated against, as a decimal string.
          examples:
            - "100.00"
          type: string
        items:
          description: Per-item breakdown of the simulated fees.
          items:
            $ref: "#/components/schemas/SimulateFeeItem"
          maxItems: 100
          type:
            - array
            - "null"
        netAmount:
          description: Amount remaining after all fees, as a decimal string.
          examples:
            - "97.70"
          type: string
        totalFee:
          description: Sum of all item fees, as a decimal string.
          examples:
            - "2.30"
          type: string
      required:
        - grossAmount
        - netAmount
        - totalFee
        - currency
        - items
      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
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
            - FUZZY
          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
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
            - FUZZY
          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.
          examples:
            - 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.
          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.
          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
    SourceBreakdownListResponse:
      additionalProperties: false
      properties:
        sources:
          description: Per-source reconciliation statistics for the window.
          items:
            $ref: "#/components/schemas/SourceBreakdownResponse"
          type:
            - array
            - "null"
      required:
        - sources
      type: object
    SourceBreakdownResponse:
      additionalProperties: false
      properties:
        currency:
          description: ISO 4217 currency code for the monetary amounts in this row.
          examples:
            - USD
          type: string
        matchRate:
          description: Percentage of this source's transactions that were matched (0-100).
          examples:
            - 95
          format: double
          type: number
        matchedTransactions:
          description: Number of matched transactions from this source.
          examples:
            - 4750
          format: int64
          type: integer
        sourceId:
          description: Identifier of the reconciliation source (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        sourceName:
          description: Human-readable name of the source.
          examples:
            - Primary Bank Account
          type: string
        totalAmount:
          description: Total monetary value of this source's transactions, as a decimal string.
          examples:
            - "500000.00"
          type: string
        totalTransactions:
          description: Total number of transactions from this source.
          examples:
            - 5000
          format: int64
          type: integer
        unmatchedAmount:
          description: Monetary value of this source's unmatched transactions, as a decimal string.
          examples:
            - "25000.00"
          type: string
        unmatchedTransactions:
          description: Number of unmatched transactions from this source.
          examples:
            - 250
          format: int64
          type: integer
      required:
        - sourceId
        - sourceName
        - totalTransactions
        - matchedTransactions
        - unmatchedTransactions
        - matchRate
        - totalAmount
        - unmatchedAmount
        - currency
      type: object
    SourceWithFieldMapStatusResponse:
      additionalProperties: false
      properties:
        archivedAt:
          description: RFC 3339 timestamp when the source was archived; absent when the source is live.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
        config:
          additionalProperties: {}
          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
          properties:
            blank_external_id:
              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
              enum:
                - REJECT
                - NEEDS_REVIEW
              type: string
            camt053:
              additionalProperties: false
              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
              properties:
                date_basis:
                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
                  enum:
                    - booking
                    - valuation
                  type: string
                external_id_source:
                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
                  enum:
                    - ntry_ref
                    - end_to_end_id
                    - tx_id
                  type: string
              type: object
            dialect:
              additionalProperties: false
              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
              properties:
                date_style:
                  enum:
                    - iso
                    - iso_offset
                    - dmy
                    - mdy
                  type: string
                decimal_style:
                  description: dot is 1234.56, comma is 1.234,56.
                  enum:
                    - dot
                    - comma
                  type: string
                delimiter:
                  enum:
                    - comma
                    - semicolon
                    - tab
                    - pipe
                  type: string
                encoding:
                  enum:
                    - utf-8
                    - utf-8-sig
                    - cp1252
                    - iso-8859-1
                  type: string
              type: object
            duplicate_key:
              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
              items:
                enum:
                  - external_id
                  - amount
                  - currency
                  - date
                  - description
                  - fee_amount
                  - fee_currency
                type: string
              minItems: 1
              type: array
              uniqueItems: true
            duplicate_key_changed_at:
              description: SERVER-OWNED. The moment duplicate-key detection last changed meaning on this source, either because duplicate_key was edited or because the field map remapped the column a declared component reads. Rows imported before it keep the key they were deduplicated under. A value sent by a client is discarded.
              format: date-time
              readOnly: true
              type: string
            duplicate_policy:
              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
              enum:
                - FLAG_AS_EXCEPTION
                - KEEP_FIRST
                - REJECT
              type: string
            fail_on_error_rate_percent:
              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
              maximum: 99
              minimum: 1
              type: integer
          type: object
        contextId:
          description: Identifier of the context this source 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
        hasFieldMaps:
          description: Whether a field map is configured for this source.
          examples:
            - true
          type: boolean
        id:
          description: Unique identifier of the source.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        name:
          description: Human-readable name of the source.
          examples:
            - Primary Bank Account
          type: string
        side:
          description: Matching side this source feeds. LEFT and RIGHT are the two sides reconciled against each other.
          enum:
            - LEFT
            - RIGHT
          examples:
            - LEFT
          type: string
        type:
          description: Origin of the source data. LEDGER is the internal ledger; BANK is a bank statement feed; GATEWAY is a payment gateway; CUSTOM is a bespoke feed; FETCHER is a discovery-engine pull.
          enum:
            - LEDGER
            - BANK
            - GATEWAY
            - CUSTOM
            - FETCHER
          examples:
            - BANK
          type: string
        updatedAt:
          description: Last update timestamp in RFC 3339 format.
          examples:
            - "2025-01-15T10:30:00Z"
          type: string
      required:
        - hasFieldMaps
        - id
        - contextId
        - name
        - type
        - side
        - config
        - createdAt
        - updatedAt
      type: object
    StartExtractionRequest:
      additionalProperties: false
      properties:
        endDate:
          description: Optional inclusive end date (RFC 3339); must be on or after startDate
          examples:
            - "2026-06-30"
          type: string
        filters:
          $ref: "#/components/schemas/ExtractionFilters"
          description: Optional extraction filters
        startDate:
          description: Optional inclusive start date (RFC 3339)
          examples:
            - "2026-06-01"
          type: string
        tables:
          additionalProperties:
            $ref: "#/components/schemas/ExtractionTableRequest"
          description: Per-table extraction configuration keyed by table name; at least one entry required
          minProperties: 1
          type: object
      required:
        - tables
      type: object
    SubmitEvidenceRequest:
      additionalProperties: false
      properties:
        comment:
          description: Comment describing the evidence
          examples:
            - Attached bank statement showing correct amount
          maxLength: 1000
          minLength: 1
          type: string
        fileUrl:
          description: Optional URL to evidence file
          examples:
            - https://storage.example.com/evidence/doc123.pdf
          maxLength: 2048
          type: string
      required:
        - comment
      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
    SummaryMetricsResponse:
      additionalProperties: false
      properties:
        criticalExposure:
          description: Total monetary exposure from critical-severity exceptions, as a decimal string.
          examples:
            - "15000.00"
          type: string
        matchRate:
          description: Percentage of transactions matched (0-100).
          examples:
            - 94.4
          format: double
          type: number
        oldestExceptionAgeHours:
          description: Age of the oldest open exception, in hours.
          examples:
            - 72.5
          format: double
          type: number
        pendingExceptions:
          description: Number of exceptions still awaiting resolution.
          examples:
            - 4
          format: int64
          type: integer
        totalMatches:
          description: Total number of matched transactions in the window.
          examples:
            - 11800
          format: int64
          type: integer
        totalTransactions:
          description: Total number of transactions in the window.
          examples:
            - 12500
          format: int64
          type: integer
      required:
        - totalTransactions
        - totalMatches
        - matchRate
        - pendingExceptions
        - criticalExposure
        - oldestExceptionAgeHours
      type: object
    SummaryReportResponse:
      additionalProperties: false
      properties:
        matchedAmount:
          description: Total monetary value of matched transactions, as a decimal string.
          examples:
            - "1180000.00"
          type: string
        matchedCount:
          description: Number of matched transactions in the window.
          examples:
            - 11800
          format: int64
          type: integer
        totalAmount:
          description: Total monetary value of all transactions, as a decimal string.
          examples:
            - "1250000.00"
          type: string
        unmatchedAmount:
          description: Total monetary value of unmatched transactions, as a decimal string.
          examples:
            - "70000.00"
          type: string
        unmatchedCount:
          description: Number of unmatched transactions in the window.
          examples:
            - 700
          format: int64
          type: integer
      required:
        - matchedCount
        - unmatchedCount
        - totalAmount
        - matchedAmount
        - unmatchedAmount
      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
      required:
        - 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
    TestConnectionResponse:
      additionalProperties: false
      properties:
        connectionId:
          description: Internal Matcher connection identifier that was tested
          examples:
            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        errorMessage:
          description: Sanitized error message when the test failed; empty on success
          type: string
        healthy:
          description: Whether the connectivity test succeeded
          type: boolean
        latencyMs:
          description: Round-trip connectivity test latency in milliseconds
          examples:
            - 42
          format: int64
          type: integer
      required:
        - connectionId
        - healthy
        - latencyMs
      type: object
    TransactionResponse:
      additionalProperties: false
      properties:
        amount:
          description: Transaction amount as a decimal string in the transaction currency (precision preserved verbatim; never a float)
          examples:
            - "1000.50"
          type: string
        contextId:
          description: Reconciliation context this transaction belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        createdAt:
          description: Creation timestamp (RFC 3339)
          examples:
            - "2025-01-15T10:30:00Z"
          format: date-time
          type: string
        currency:
          description: ISO 4217 currency code of the amount
          examples:
            - USD
          type: string
        date:
          description: Transaction value date (RFC 3339)
          examples:
            - "2025-01-15T00:00:00Z"
          format: date-time
          type: string
        dedupeKey:
          description: "Read-only: the duplicate-key value this row was imported under, derived from the source's duplicate key declaration at import time. A source can change that declaration later, so this is the only place that says which identity THIS row carries. Prefixed v1 when the key spells out the fields it was derived from, v1h when those fields were hashed because the spelled-out key was too long to index."
          examples:
            - v1|external_id=9:TXN-12345
          type: string
        description:
          description: Free-text description carried from the source
          examples:
            - Wire transfer from ABC Corp
          type: string
        externalId:
          description: External identifier carried from the source system
          examples:
            - TXN-12345
          type: string
        extractionStatus:
          description: "Field-extraction status: PENDING (queued), COMPLETE (fields parsed), FAILED (extraction error)"
          enum:
            - PENDING
            - COMPLETE
            - FAILED
          examples:
            - COMPLETE
          type: string
        id:
          description: Unique identifier for the transaction
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        jobId:
          description: Ingestion job that produced this transaction
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        metadata:
          additionalProperties: {}
          description: "Normalized source metadata: unmapped source columns the engine projects into composite match keys and FX-conversion inputs (e.g. counterparty, bank_transaction_code, fx_rate). Arbitrary key/value, tenant-scoped to the caller's own data."
          type: object
        sourceId:
          description: Source this transaction belongs to
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        status:
          description: "Matching status: UNMATCHED (no match found), MATCHED (reconciled), IGNORED (excluded from reconciliation by an operator), PENDING_REVIEW (imported under the blank-external-id review policy and awaiting an operator decision)"
          enum:
            - UNMATCHED
            - MATCHED
            - IGNORED
            - PENDING_REVIEW
          examples:
            - UNMATCHED
          type: string
      required:
        - id
        - jobId
        - sourceId
        - contextId
        - externalId
        - dedupeKey
        - amount
        - currency
        - date
        - status
        - extractionStatus
        - createdAt
      type: object
    TrendMetricsResponse:
      additionalProperties: false
      properties:
        dates:
          description: Ordered list of dates (one per data point) labelling the parallel trend series.
          items:
            type: string
          maxItems: 366
          type:
            - array
            - "null"
        exceptions:
          description: Per-date count of exceptions raised, aligned by index with dates.
          items:
            format: int64
            type: integer
          maxItems: 366
          type:
            - array
            - "null"
        ingestion:
          description: Per-date count of ingested transactions, aligned by index with dates.
          items:
            format: int64
            type: integer
          maxItems: 366
          type:
            - array
            - "null"
        matchRates:
          description: Per-date match rate percentage (0-100), aligned by index with dates.
          items:
            format: double
            type: number
          maxItems: 366
          type:
            - array
            - "null"
        matches:
          description: Per-date count of matched transactions, aligned by index with dates.
          items:
            format: int64
            type: integer
          maxItems: 366
          type:
            - array
            - "null"
      required:
        - dates
        - ingestion
        - matches
        - exceptions
        - matchRates
      type: object
    UnattributedAdjustmentResponse:
      additionalProperties: false
      properties:
        currency:
          description: ISO 4217 currency code of the adjustments in this total.
          examples:
            - USD
          type: string
        total:
          description: "Signed sum of the recorded adjustments no row includes: positive for debits, negative for credits, as a decimal string. Each one's match group or transaction reaches more than one row, and the report never splits an amount."
          examples:
            - "3.50"
          type: string
      required:
        - currency
        - total
      type: object
    UnmatchRequest:
      additionalProperties: false
      properties:
        reason:
          description: Reason the match group is being broken
          examples:
            - incorrect match - amounts do not match
          minLength: 1
          type: string
      required:
        - reason
      type: object
    UnmatchedItemResponse:
      additionalProperties: false
      properties:
        amount:
          description: Transaction amount as a decimal string in the transaction's currency.
          examples:
            - "1250.50"
          type: string
        currency:
          description: ISO 4217 currency code of the transaction amount.
          examples:
            - USD
          type: string
        date:
          description: Transaction value date (RFC 3339 timestamp, UTC).
          examples:
            - "2025-01-15T10:30:00Z"
          format: date-time
          type: string
        dueAt:
          description: SLA due date for resolving the associated exception, if any (RFC 3339 timestamp, UTC).
          examples:
            - "2025-02-15T10:30:00Z"
          format: date-time
          type: string
        exceptionId:
          description: Identifier of the exception raised for this transaction, if any (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440003
          format: uuid
          type: string
        sourceId:
          description: Identifier of the source the transaction came from (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        sourceName:
          description: Human-readable name of the source the transaction came from; omitted when the source name is unavailable.
          examples:
            - Acquirer Settlement File
          type: string
        status:
          description: Current transaction status carried from the ingestion domain (e.g. UNMATCHED, PENDING_REVIEW).
          examples:
            - PENDING
          type: string
        transactionId:
          description: Identifier of the unmatched transaction (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
      required:
        - transactionId
        - sourceId
        - amount
        - currency
        - status
        - date
      type: object
    UpdateAggregatorConnectionRequest:
      additionalProperties: false
      properties:
        accountRef:
          description: Opaque vendor account reference (Pluggy itemId, Belvo link id). Supply it to bind (or re-bind) the connection after the vendor's consent widget returns one; omit it to leave the stored value untouched.
          examples:
            - a1b2c3d4-5678-90ab-cdef-1234567890ab
          type: string
        baseUrl:
          description: Vendor API base URL, stored as the connection host. Omit it to leave the stored URL untouched.
          examples:
            - https://api.pluggy.ai
          format: uri
          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. Omit it to leave the stored name untouched.
          examples:
            - pluggy-main
          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
      type: object
    UpdateContextRequest:
      additionalProperties: false
      properties:
        agedBreakCalendar:
          description: Business-day calendar the aging threshold is measured against. Empty string clears it (raw calendar days); omit to leave it unchanged.
          examples:
            - BR_ANBIMA
          type: string
        agedBreakThresholdDays:
          description: Open-item aging SLA in business days. A positive value enables/changes aging; 0 disables it (clears the threshold); omit to leave it unchanged.
          examples:
            - 30
          format: int64
          type: integer
        autoMatchOnUpload:
          description: When true, a match run is triggered automatically after a file upload completes.
          examples:
            - true
          type: boolean
        feeNormalization:
          description: "Fee normalization mode. NET compares amounts after fees are deducted; GROSS compares amounts before fees. Send an empty string to clear the mode; omit to leave it unchanged. (No enum constraint: unlike create, the update path accepts the empty string to clear.)"
          examples:
            - NET
          type: string
        feeToleranceAbs:
          description: Absolute fee tolerance as a decimal string in the context currency.
          examples:
            - "0.01"
          type: string
        feeTolerancePct:
          description: Percentage fee tolerance as a decimal string (0.5 means 0.5%).
          examples:
            - "0.5"
          type: string
        interval:
          description: Execution interval label for the context (e.g. daily, weekly).
          examples:
            - weekly
          maxLength: 100
          type: string
        name:
          description: New human-readable name of the reconciliation context.
          examples:
            - Bank Reconciliation Q2
          maxLength: 100
          type: string
        signConvention:
          description: "How this context's data carries sign. SAME: a payment carries the same sign as what it settles, so a negative amount is a reversal. OPPOSITE: a payment carries the opposite sign of the invoice it settles. Omit to leave it unchanged. In 1:N contexts only payments of the declared sign are allocated to an invoice, and in N:M contexts a short-paid invoice keeps an open balance only when it is positive under SAME, or when the rule's sign mode is opposite under OPPOSITE; any other short payment stays unmatched; a carried open balance settles on a payment of the declared sign or on a reversal from the invoice's own side, and a row from an archived source stays unmatched. It cannot change once the context has carried a partial balance, or while a match run is in progress."
          enum:
            - SAME
            - OPPOSITE
          examples:
            - OPPOSITE
          type: string
        status:
          description: Lifecycle status to transition to. ACTIVE runs the context; PAUSED suspends scheduling; ARCHIVED retires it.
          enum:
            - ACTIVE
            - PAUSED
            - ARCHIVED
          examples:
            - ACTIVE
          type: string
        type:
          description: Reconciliation topology. 1:1 matches one left transaction to one right transaction; 1:N matches one transaction against many on the other side; N:M matches groups on both sides.
          enum:
            - "1:1"
            - 1:N
            - N:M
          examples:
            - 1:N
          type: string
      type: object
    UpdateFeeRuleRequest:
      additionalProperties: false
      properties:
        feeScheduleId:
          description: UUID of the fee schedule this rule applies when its predicates match.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          type: string
        name:
          description: Human-readable name of the fee rule.
          examples:
            - Updated Rule
          type: string
        predicates:
          description: Predicates (ANDed together) that a transaction's metadata must satisfy for this rule to apply. Replaces the existing predicate set when provided.
          items:
            $ref: "#/components/schemas/FieldPredicateRequest"
          type: array
        priority:
          description: Evaluation priority; lower numbers are evaluated first. Must remain unique within the context. LEFT, RIGHT, and ANY rules share the same priority space.
          examples:
            - 1
          format: int64
          type: integer
        side:
          description: Side the rule applies to. LEFT and RIGHT target one reconciliation side; ANY matches transactions on either side.
          enum:
            - LEFT
            - RIGHT
            - ANY
          examples:
            - LEFT
          type: string
      type: object
    UpdateFeeScheduleRequest:
      additionalProperties: false
      properties:
        applicationOrder:
          description: How items combine. PARALLEL applies every item to the same gross base; CASCADING applies each item to the net remaining after prior items.
          enum:
            - PARALLEL
            - CASCADING
          examples:
            - CASCADING
          type: string
        name:
          description: New human-readable name of the fee schedule.
          examples:
            - Updated Schedule
          type: string
        roundingMode:
          description: Rounding strategy. HALF_UP rounds halves away from zero; BANKERS rounds halves to the nearest even digit; FLOOR rounds down; CEIL rounds up; TRUNCATE drops extra digits.
          enum:
            - HALF_UP
            - BANKERS
            - FLOOR
            - CEIL
            - TRUNCATE
          examples:
            - BANKERS
          type: string
        roundingScale:
          description: Number of decimal places fee amounts are rounded to.
          examples:
            - 4
          format: int64
          type: integer
      type: object
    UpdateFieldMapRequest:
      additionalProperties: false
      properties:
        mapping:
          additionalProperties: {}
          description: Field-mapping object that normalizes a source's raw columns to canonical transaction fields.
          type: object
      required:
        - mapping
      type: object
    UpdateMatchRuleRequest:
      additionalProperties: false
      properties:
        config:
          additionalProperties: {}
          description: "Rule-specific configuration object. Includes the built-in toggles (matchAmount, matchCurrency, matchDate, matchReference) and tolerance/lag parameters, plus an optional composite-key array matchFields: [{ field, mode, tolerance? }] where mode is one of required, conditional, or off, and tolerance is an optional per-field relaxation ({ absTolerance?, percentTolerance? } for numeric or { stringMode: exact|fold } for text). Optional date keys (opt-in; default behavior is raw UTC days): timezone (an IANA zone name, e.g. America/Sao_Paulo, buckets dates by local sales-day before the date window/lag is applied), calendar (a vendored business-day calendar name, US_FED or BR_ANBIMA — on TOLERANCE it makes dateWindowDays count business days; on DATE_LAG it pairs with businessDayMode), and businessDayMode (DATE_LAG only; makes minDays/maxDays count business days under calendar). Optional signMode key (one of same, opposite, ignore; default same) selects the axis used when the rule compares amounts: same matches signed amounts (legacy behavior); opposite matches a value against its negation (a -100 refund reconciles against a +100 charge); ignore compares magnitudes only. It is consulted only when the rule actually compares amounts (matchAmount on EXACT/FUZZY, the tolerance band on TOLERANCE); on a rule that does not compare amounts it is accepted but inert."
          type: object
        priority:
          description: Execution priority; lower numbers run first. Must remain unique within the context.
          examples:
            - 2
          format: int64
          maximum: 1000
          minimum: 1
          type: integer
        type:
          description: Matching strategy. EXACT requires identical field values; TOLERANCE allows configured numeric slack; DATE_LAG allows a configured date offset between sides; FUZZY matches on normalized/similarity-scored references (free-text memos, truncated refs) and always proposes for review (never auto-confirms).
          enum:
            - EXACT
            - TOLERANCE
            - DATE_LAG
            - FUZZY
          examples:
            - TOLERANCE
          type: string
      type: object
    UpdateScheduleRequest:
      additionalProperties: false
      properties:
        cronExpression:
          description: Cron expression (5-field) defining when the reconciliation runs.
          examples:
            - 0 6 * * *
          maxLength: 100
          type: string
        enabled:
          description: Whether the schedule is active.
          examples:
            - false
          type: boolean
      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.
          examples:
            - 30m
          maxLength: 100
          type: string
        transportConfig:
          $ref: "#/components/schemas/SourceBindingTransportConfigRequest"
          description: File-rail transport configuration. Applies only to file-rail bindings.
      type: object
    UpdateSourceRequest:
      additionalProperties: false
      properties:
        config:
          additionalProperties: {}
          description: "Source-specific configuration object. Cross-key rules the schema cannot express: a duplicate_key component this source's field map does not fill is refused, because a key over an always-empty field makes every row a duplicate of every other; a source bound to an aggregator connection (reserved key connection_config_name) cannot carry a duplicate_key of its own, and a config holding both is refused in either direction; and editing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under, so a duplicate straddling the change is knowingly not detected."
          properties:
            blank_external_id:
              description: What happens to a row whose mapped external id is blank. REJECT (the default when the key is absent) fails the row. NEEDS_REVIEW imports it under a synthetic reference with status PENDING_REVIEW, so a blank reference becomes a reviewable import instead of an import failure.
              enum:
                - REJECT
                - NEEDS_REVIEW
              type: string
            camt053:
              additionalProperties: false
              description: How this source's camt.053 files map onto the canonical fields. Every other field is fixed by ISO 20022 itself. An absent object, or an absent sub-key, keeps the ISO defaults (booking, ntry_ref).
              properties:
                date_basis:
                  description: "Entry date element: booking is BookgDt/Dt, valuation is ValDt/Dt. Default booking."
                  enum:
                    - booking
                    - valuation
                  type: string
                external_id_source:
                  description: "Entry reference element: ntry_ref is NtryRef, end_to_end_id is NtryDtls/TxDtls/Refs/EndToEndId, tx_id is NtryDtls/TxDtls/Refs/TxId. Default ntry_ref."
                  enum:
                    - ntry_ref
                    - end_to_end_id
                    - tx_id
                  type: string
              type: object
            dialect:
              additionalProperties: false
              description: How this source's delimited files are encoded and formatted. Declaration-driven only — there is no auto-detection. An absent object, or an absent sub-key, keeps the defaults (utf-8, comma, dot, iso).
              properties:
                date_style:
                  enum:
                    - iso
                    - iso_offset
                    - dmy
                    - mdy
                  type: string
                decimal_style:
                  description: dot is 1234.56, comma is 1.234,56.
                  enum:
                    - dot
                    - comma
                  type: string
                delimiter:
                  enum:
                    - comma
                    - semicolon
                    - tab
                    - pipe
                  type: string
                encoding:
                  enum:
                    - utf-8
                    - utf-8-sig
                    - cp1252
                    - iso-8859-1
                  type: string
              type: object
            duplicate_key:
              description: The ordered list of mapped fields that make two rows the same row. Absent means external_id alone. On a source bound to an aggregator connection the aggregator retracts a movement by naming its external id, so that id has to stay the row identity.
              items:
                enum:
                  - external_id
                  - amount
                  - currency
                  - date
                  - description
                  - fee_amount
                  - fee_currency
                type: string
              minItems: 1
              type: array
              uniqueItems: true
            duplicate_policy:
              description: What happens to a row that repeats this source's duplicate key. FLAG_AS_EXCEPTION (the default when the key is absent) keeps the repeat out of the import and raises a duplicate exception on the row it repeated. KEEP_FIRST drops the repeat and raises nothing, so a collision leaves no trace anyone can act on. REJECT counts the repeat as an import error.
              enum:
                - FLAG_AS_EXCEPTION
                - KEEP_FIRST
                - REJECT
              type: string
            fail_on_error_rate_percent:
              description: "Fail the whole import when the percentage of failed rows exceeds this whole number. Absent means never auto-fail. The ceiling is 99, not 100: the comparison is strict, so 100 could never fire."
              maximum: 99
              minimum: 1
              type: integer
          type: object
        name:
          description: New human-readable name of the source.
          examples:
            - Secondary Bank Account
          maxLength: 50
          type: string
        side:
          description: Matching side this source feeds. LEFT and RIGHT are the two sides reconciled against each other. A change is refused with a 409 once the context has carried a partial balance, or while a match run is in progress.
          enum:
            - LEFT
            - RIGHT
          examples:
            - RIGHT
          type: string
        type:
          description: Origin of the source data. LEDGER is the internal ledger; BANK is a bank statement feed; GATEWAY is a payment gateway; CUSTOM is a bespoke feed; FETCHER is a discovery-engine pull.
          enum:
            - LEDGER
            - BANK
            - GATEWAY
            - CUSTOM
            - FETCHER
          examples:
            - LEDGER
          type: string
      type: object
    UpsertActorMappingRequest:
      additionalProperties: false
      properties:
        displayName:
          description: Human-readable display name for the actor; optional, but at least one of displayName or email must be provided
          examples:
            - John Doe
          type:
            - string
            - "null"
        email:
          description: Email address of the actor; optional, but at least one of displayName or email must be provided
          examples:
            - john.doe@example.com
          format: email
          type:
            - string
            - "null"
      type: object
    Upstream:
      additionalProperties: false
      properties:
        code:
          description: The upstream provider's own error code, verbatim.
          examples:
            - E4001
          type: string
        message:
          description: The upstream provider's own error message, verbatim (bounded, never its raw response body).
          examples:
            - account not found at provider
          type: string
      type: object
    VarianceReportRowResponse:
      additionalProperties: false
      properties:
        adjustmentsApplied:
          description: "Signed sum of the adjustments an operator recorded against this row: positive for debits, negative for credits, as a decimal string."
          examples:
            - "200.00"
          type: string
        currency:
          description: ISO 4217 currency code for the amounts in this row.
          examples:
            - USD
          type: string
        feeScheduleId:
          description: Identifier of the fee schedule the variance is computed against (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        feeScheduleName:
          description: Human-readable name of the fee schedule.
          examples:
            - INTERCHANGE
          type: string
        netVariance:
          description: Signed difference between actual and expected totals (actual minus expected), as a decimal string. This is the RAW difference and ignores any adjustment an operator recorded.
          examples:
            - "-200.00"
          type: string
        outstandingVariance:
          description: Net variance plus applied adjustments — the difference nobody has explained yet, as a decimal string. Zero means fully explained.
          examples:
            - "0.00"
          type: string
        sourceId:
          description: Identifier of the source for this variance row (UUID).
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        totalActual:
          description: Actual fee total observed, as a decimal string.
          examples:
            - "4800.00"
          type: string
        totalExpected:
          description: Expected fee total per the schedule, as a decimal string.
          examples:
            - "5000.00"
          type: string
        variancePct:
          description: Net variance as a percentage of the expected total, as a decimal string; omitted when expected total is zero.
          examples:
            - "-4.00"
          type: string
      required:
        - sourceId
        - currency
        - feeScheduleId
        - feeScheduleName
        - totalExpected
        - totalActual
        - netVariance
        - adjustmentsApplied
        - outstandingVariance
      type: object
    VolumeStatsResponse:
      additionalProperties: false
      properties:
        matchedAmount:
          description: Total monetary value of matched transactions, as a decimal string in the source currency.
          examples:
            - "1180000.00"
          type: string
        matchedTransactions:
          description: Number of transactions that were successfully matched.
          examples:
            - 11800
          format: int64
          type: integer
        periodEnd:
          description: Inclusive end of the reporting window (RFC 3339 timestamp, UTC).
          examples:
            - "2025-01-31T23:59:59Z"
          format: date-time
          type: string
        periodStart:
          description: Inclusive start of the reporting window (RFC 3339 timestamp, UTC).
          examples:
            - "2025-01-01T00:00:00Z"
          format: date-time
          type: string
        totalAmount:
          description: Total monetary value of all transactions, as a decimal string in the source currency.
          examples:
            - "1250000.00"
          type: string
        totalTransactions:
          description: Total number of transactions in the reporting window.
          examples:
            - 12500
          format: int64
          type: integer
        unmatchedAmount:
          description: Total monetary value of unmatched transactions, as a decimal string in the source currency.
          examples:
            - "70000.00"
          type: string
        unmatchedCount:
          description: Number of transactions left unmatched.
          examples:
            - 700
          format: int64
          type: integer
      required:
        - totalTransactions
        - matchedTransactions
        - unmatchedCount
        - totalAmount
        - matchedAmount
        - unmatchedAmount
        - periodStart
        - periodEnd
      type: object
    ErrorResponse:
      description: Flat error body that Matcher returns when it refuses a request before the operation runs.
      type: object
      required:
        - code
        - title
        - message
      properties:
        code:
          type: string
          description: Stable error code.
          example: MTCH-0003
        title:
          type: string
          description: HTTP status text.
          example: Unauthorized
        message:
          type: string
          description: Human-readable error message.
          example: missing authorization token
    RateLimitErrorResponse:
      description: Flat body that the rate limiter returns. `code` is the HTTP status as a number.
      type: object
      required:
        - code
        - title
        - message
      properties:
        code:
          type: integer
          description: HTTP status code.
          example: 429
        title:
          type: string
          description: Error type.
          example: rate_limit_exceeded
        message:
          type: string
          description: Human-readable error message.
          example: rate limit exceeded
  examples:

    400-invalid-pagination-parameters:
      summary: Invalid pagination parameters
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The pagination cursor could not be decoded; omit it to start from the first page, or use the exact cursor value returned by a previous response
        code: MTCH-0001
    400-invalid-context-payload:
      summary: Invalid context payload
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: One of the inline sources or match rules in this context payload is invalid; the context was not created. Fix the referenced item and try again.
        code: MTCH-0001
    mtch-0001-context-name-is-required:
      summary: Context name is required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: a reconciliation context name is required; provide a name and try again
        code: MTCH-0001
    mtch-0101-a-reconciliation-context-with-this-name-already-exists:
      summary: A reconciliation context with this name already exists
      value:
        type: https://errors.lerian.studio/v1/MTCH-0101
        title: Conflict
        status: 409
        detail: A reconciliation context with this name already exists; the context was not created. Choose a different name.
        code: MTCH-0101
    mtch-0102-priority-already-exists-in-context:
      summary: Priority already exists in context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0102
        title: Conflict
        status: 409
        detail: A match rule with this priority already exists in this context; choose a different priority and try again
        code: MTCH-0102
    mtch-0110-context-not-found:
      summary: Context not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No reconciliation context matches this id; check the context id and try again.
        code: MTCH-0005
    mtch-0103-cannot-pause-context-in-draft-status-invalid-state-transitio:
      summary: 'Cannot pause context in DRAFT status: invalid state transition'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0103
        title: Conflict
        status: 409
        detail: A draft context cannot be paused directly; activate it first, then pause it
        code: MTCH-0103
    mtch-0104-archived-context-cannot-be-modified:
      summary: Archived context cannot be modified
      value:
        type: https://errors.lerian.studio/v1/MTCH-0104
        title: Conflict
        status: 409
        detail: This context is archived and cannot be modified; restore it first if you need to change its configuration
        code: MTCH-0104
    mtch-0109-new-context-name-is-required-for-clone:
      summary: New context name is required for clone
      value:
        type: https://errors.lerian.studio/v1/MTCH-0109
        title: Bad Request
        status: 400
        detail: A name for the new context is required to clone this context.
        code: MTCH-0109
    mtch-0001-build-cloned-context-entity-context-name-exceeds-100-charact:
      summary: 'Build cloned context entity: context name exceeds 100 characters'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: the reconciliation context name exceeds the 100-character limit; shorten it and try again
        code: MTCH-0001
    mtch-0101-a-context-with-this-name-already-exists:
      summary: A context with this name already exists
      value:
        type: https://errors.lerian.studio/v1/MTCH-0101
        title: Conflict
        status: 409
        detail: 'The clone was not created: either the new name is already used by another context, or this context has a source tied to a Fetcher connection, and a Fetcher connection can only ever back one source, so that source cannot be copied. Choose a different name, or clone again with includeSources set to false to copy the context without any sources, then add the sources you need to the clone.'
        code: MTCH-0101
    400-invalid-match-rule-payload:
      summary: Invalid match rule payload
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The match rule's config is invalid; the rule was not created. Fix the config and try again.
        code: MTCH-0001
    mtch-0113-match-rule-not-found:
      summary: Match rule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0113
        title: Not Found
        status: 404
        detail: No match rule matches this id in this context. Check the match rule id and try again.
        code: MTCH-0113
    mtch-0001-config-is-required:
      summary: Config is required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: this match rule needs a configuration; provide one and try again
        code: MTCH-0001
    400-missing-rule-ids:
      summary: Missing rule IDs
      value:
        title: Bad Request
        status: 400
        detail: missing rule IDs
    400-invalid-source-payload:
      summary: Invalid source payload
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The source configuration could not be serialized, or exceeds the size, nesting, or key-count limit; correct it and try again
        code: MTCH-0001
    mtch-0001-source-name-exceeds-50-characters:
      summary: Source name exceeds 50 characters
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: the source name exceeds the 50-character limit; shorten it and try again
        code: MTCH-0001
    mtch-0111-source-not-found:
      summary: Source not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0111
        title: Not Found
        status: 404
        detail: The source could not be found; check the source id and try again
        code: MTCH-0111
    mtch-0112-field-map-not-found:
      summary: Field map not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0112
        title: Not Found
        status: 404
        detail: The field map could not be found; check the field map id and try again
        code: MTCH-0112
    mtch-0001-invalid-field-map-mapping-missing-required-keys-amount:
      summary: 'Invalid field map mapping: missing required keys [amount]'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: the field map mapping is invalid; check the mapped column names and try again
        code: MTCH-0001
    mtch-0001-mapping-is-required:
      summary: Mapping is required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: a field map must map at least one column; add a mapping and try again
        code: MTCH-0001
    400-invalid-fee-schedule-items:
      summary: Invalid fee schedule items
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: One or more fee schedule items are invalid. The structure type must be flat, percentage, tiered, or expression; flat needs a string amount, percentage needs a string rate (0 to 1), tiered needs a tiers array, and expression needs a parseable formula; fix the item and try again.
        code: MTCH-0001
    mtch-0001-create-fee-schedule-fee-schedule-name-fee-schedule-name-is-r:
      summary: 'Create fee schedule: fee schedule name: fee schedule name is required'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The fee schedule request is invalid; check the schedule's name, items, and rounding/application-order settings and try again
        code: MTCH-0001
    mtch-0115-fee-schedule-not-found:
      summary: Fee schedule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0115
        title: Not Found
        status: 404
        detail: The fee schedule could not be found; check the fee schedule id and try again
        code: MTCH-0115
    mtch-0001-fee-schedule-name-is-required:
      summary: Fee schedule name is required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The fee schedule update is invalid; check the name, application order, and rounding settings and try again
        code: MTCH-0001
    mtch-0108-fee-schedule-is-referenced-by-fee-rules:
      summary: Fee schedule is referenced by fee rules
      value:
        type: https://errors.lerian.studio/v1/MTCH-0108
        title: Conflict
        status: 409
        detail: This fee schedule is still referenced by fee rules; nothing was deleted. Remove the referencing fee rules, then retry the deletion.
        errors:
          - location: fee-schedule.delete.blocking-contexts
            value:
              references:
                - id: 11111111-1111-1111-1111-111111111111
                  name: Card settlement
              count: 1
        code: MTCH-0108
    mtch-0108-fee-schedule-is-still-in-use:
      summary: Fee schedule is still in use
      value:
        type: https://errors.lerian.studio/v1/MTCH-0108
        title: Conflict
        status: 409
        detail: This fee schedule is referenced by fee verification history; nothing was deleted. That history is preserved for audit and cannot be removed, so the schedule cannot be deleted while it exists. Keep it, and create a new fee schedule if different terms are needed for future rules.
        code: MTCH-0108
    400-invalid-gross-amount:
      summary: Invalid gross amount
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The gross amount is not a valid decimal number. Check the amount and try again.
        code: MTCH-0001
    mtch-0001-gross-currency-invalid-currency:
      summary: 'Gross currency: invalid currency'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The simulation could not run for this schedule; the cause may be the gross amount or currency you provided, how the schedule's own fee items are configured, or — if the schedule includes an expression-based fee — the fact that a standalone simulation carries no transaction metadata for that expression to evaluate. Check those settings, or simulate against a real transaction instead, then try again.
        code: MTCH-0001
    mtch-0001-create-schedule-entity-invalid-cron-expression-cannot-comput:
      summary: 'Create schedule entity: invalid cron expression: cannot compute first...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The cron expression is invalid; use the standard 5-field cron format (minute hour day-of-month month day-of-week) and make sure it names a date that actually occurs (for example, not February 30), then try again
        code: MTCH-0001
    mtch-0116-schedule-not-found:
      summary: Schedule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0116
        title: Not Found
        status: 404
        detail: No reconciliation schedule matches this id. Check the schedule id and try again.
        code: MTCH-0116
    mtch-0001-update-schedule-entity-invalid-cron-expression-cannot-comput:
      summary: 'Update schedule entity: invalid cron expression: cannot compute first...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The cron expression is invalid; use the standard 5-field cron format (minute hour day-of-month month day-of-week) and make sure it names a date that actually occurs (for example, not February 30), then try again
        code: MTCH-0001
    400-invalid-fee-schedule-id:
      summary: Invalid fee schedule id
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The fee schedule id is not a valid UUID; no fee rule was created. Check the fee schedule id and try again.
        code: MTCH-0001
    mtch-0001-create-fee-rule-fee-rule-count-exceeds-the-maximum-allowed-p:
      summary: 'Create fee rule: fee rule count exceeds the maximum allowed per context'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: this context has reached its maximum number of fee rules; remove an existing rule before adding another
        code: MTCH-0001
    mtch-0107-a-fee-rule-with-this-priority-already-exists-in-the-context:
      summary: A fee rule with this priority already exists in the context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0107
        title: Conflict
        status: 409
        detail: A fee rule with this priority already exists in this context; choose a different priority and try again
        code: MTCH-0107
    mtch-0101-a-fee-rule-with-this-name-already-exists-in-the-context:
      summary: A fee rule with this name already exists in the context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0101
        title: Conflict
        status: 409
        detail: A fee rule with this name already exists in this context; choose a different name.
        code: MTCH-0101
    mtch-0114-fee-rule-not-found:
      summary: Fee rule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0114
        title: Not Found
        status: 404
        detail: The fee rule could not be found; check the fee rule id and try again
        code: MTCH-0114
    mtch-0001-update-fee-rule-fee-rule-name-fee-rule-name-is-required:
      summary: 'Update fee rule: fee rule name: fee rule name is required'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: a fee rule name is required; provide a name and try again
        code: MTCH-0001
    mtch-0012-context-is-not-active:
      summary: Context is not active
      value:
        type: https://errors.lerian.studio/v1/MTCH-0012
        title: Forbidden
        status: 403
        detail: context is not active
        code: MTCH-0012
    mtch-0005-context-not-found:
      summary: Context not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No reconciliation context matches this id; check the context id and try again.
        code: MTCH-0005
    400-summary-report-type-not-supported-for-async-export:
      summary: SUMMARY report type not supported for async export
      value:
        title: Bad Request
        status: 400
        detail: The summary report is not available as an export job; no export job was created. Ask for one of the other report types instead.
    mtch-0008-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0008
        title: Service Unavailable
        status: 503
        detail: internal error
        code: MTCH-0008
    400-invalid-filter-parameters:
      summary: Invalid filter parameters
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The date range or a text filter (assigned_to, external_system, or search) is invalid. Correct the filter value and try again.
        code: MTCH-0001
    mtch-0502-dispute-not-found:
      summary: Dispute not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0502
        title: Not Found
        status: 404
        detail: No dispute matches this id. Check the dispute id and try again.
        code: MTCH-0502
    400-dispute-resolution-is-required:
      summary: Dispute resolution is required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: A resolution is required to resolve this dispute.
        code: MTCH-0001
    mtch-0006-win-dispute-invalid-dispute-transition:
      summary: 'Win dispute: invalid dispute transition'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0006
        title: Unprocessable Entity
        status: 422
        detail: The dispute cannot move to the requested status from its current status; check the dispute's current status and use one of its allowed next steps
        code: MTCH-0006
    422-validation-failed:
      summary: Validation failed
      value:
        title: Unprocessable Entity
        status: 422
        detail: validation failed
    400-evidence-comment-is-required:
      summary: Evidence comment is required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: Evidence requires a comment; add one before submitting.
        code: MTCH-0001
    mtch-0006-add-evidence-cannot-add-evidence-in-current-state:
      summary: 'Add evidence: cannot add evidence in current state'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0006
        title: Unprocessable Entity
        status: 422
        detail: Evidence can only be added to a dispute that is open or waiting on evidence; check the dispute's current status before submitting evidence
        code: MTCH-0006
    400-invalid-exception-id:
      summary: Invalid exception id
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: One or more ids in this request are not valid exception ids; no exceptions were assigned. Check the exception ids and try again.
        code: MTCH-0001
    mtch-0501-exception-not-found:
      summary: Exception not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0501
        title: Not Found
        status: 404
        detail: No exception matches this id. Check the exception id and try again.
        code: MTCH-0501
    400-resolution-notes-are-required:
      summary: Resolution notes are required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: Resolution notes are required; include a note describing the resolution and try again
        code: MTCH-0001
    mtch-0503-exception-cannot-be-resolved-in-current-state:
      summary: Exception cannot be resolved in current state
      value:
        type: https://errors.lerian.studio/v1/MTCH-0503
        title: Unprocessable Entity
        status: 422
        detail: This exception is not open or assigned, so it cannot be resolved right now; nothing was changed. Reload the exception to see its current status, then retry a valid action.
        code: MTCH-0503
    400-validation-failed:
      summary: Validation failed
      value:
        title: Bad Request
        status: 400
        detail: validation failed
        errors:
          - message: unexpected end of JSON input
            location: body
            value: '{'
    mtch-0509-connector-not-configured-for-target-system:
      summary: Connector not configured for target system
      value:
        type: https://errors.lerian.studio/v1/MTCH-0509
        title: Unprocessable Entity
        status: 422
        detail: The connector for this dispatch target is not configured on this deployment; the exception was not dispatched. Choose a different target, or contact your administrator to configure this connector.
        code: MTCH-0509
    400-dispute-category-is-required:
      summary: Dispute category is required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: A dispute category is required to open a dispute.
        code: MTCH-0001
    400-comment-content-is-required:
      summary: Comment content is required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: Comment content is required; add text before submitting.
        code: MTCH-0001
    400-comment-id-is-required:
      summary: Comment id is required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: A comment id is required to delete a comment.
        code: MTCH-0001
    mtch-0004-only-the-comment-author-can-delete-their-comment:
      summary: Only the comment author can delete their comment
      value:
        type: https://errors.lerian.studio/v1/MTCH-0004
        title: Forbidden
        status: 403
        detail: only the comment author can delete their comment
        code: MTCH-0004
    mtch-0507-comment-not-found:
      summary: Comment not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0507
        title: Not Found
        status: 404
        detail: No comment matches this id for this exception; the comment was not deleted. Check the comment id and try again.
        code: MTCH-0507
    mtch-0005-export-job-not-found:
      summary: Export job not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No export job matches this id for your workspace. Check the export job id and try again.
        code: MTCH-0005
    mtch-0007-job-is-already-in-a-terminal-state:
      summary: Job is already in a terminal state
      value:
        type: https://errors.lerian.studio/v1/MTCH-0007
        title: Conflict
        status: 409
        detail: This export job has already succeeded, failed, expired, or been cancelled, so there is nothing left to cancel.
        code: MTCH-0007
    mtch-0007-export-job-is-not-ready-for-download:
      summary: Export job is not ready for download
      value:
        type: https://errors.lerian.studio/v1/MTCH-0007
        title: Conflict
        status: 409
        detail: "This export job does not have a file ready to download yet; nothing was downloaded. Check the job's status: if it is still processing, wait and try again; if it failed, was canceled, or expired, start a new export."
        code: MTCH-0007
    410-export-file-has-expired:
      summary: Export file has expired
      value:
        title: Gone
        status: 410
        detail: export file has expired
    mtch-0019-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0019
        title: Service Unavailable
        status: 503
        detail: Object storage is unavailable; retry after storage recovers, or ask an administrator to configure storage if the failure continues.
        code: MTCH-0019
    400-invalid-actor-filter:
      summary: Invalid actor filter
      value:
        title: Bad Request
        status: 400
        detail: 'The actor filter is too long: it must be 255 bytes or fewer. Shorten the actor filter and try again.'
    mtch-0005-audit-log-not-found:
      summary: Audit log not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The audit log could not be found; check the audit log id and try again.
        code: MTCH-0005
    400-at-least-one-of-displayname-or-email-must-be-provided:
      summary: At least one of displayName or email must be provided
      value:
        title: Bad Request
        status: 400
        detail: An actor mapping needs a display name or an email address, and this request supplies neither; the mapping was not applied. Provide displayName or email and try again.
    mtch-0005-actor-mapping-not-found:
      summary: Actor mapping not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The actor mapping could not be found; check the actor id and try again
        code: MTCH-0005
    400-from-must-be-a-valid-date-yyyy-mm-dd-or-rfc3339:
      summary: from must be a valid date (YYYY-MM-DD or RFC3339)
      value:
        title: Bad Request
        status: 400
        detail: The from filter is not a valid date. Use YYYY-MM-DD or a full RFC 3339 timestamp, then try again.
    mtch-0005-archive-not-found:
      summary: Archive not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No archive matches this id. Check the archive id and try again.
        code: MTCH-0005
    mtch-0306-job-not-found:
      summary: Job not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0306
        title: Not Found
        status: 404
        detail: The ingestion job could not be found. Check the job id and try again.
        code: MTCH-0306
    400-file-is-required:
      summary: File is required
      value:
        title: Bad Request
        status: 400
        detail: file is required
    mtch-0303-format-field-is-required-for-xml-uploads-and-must-precede-th:
      summary: Format field is required for .xml uploads and must precede the file part
      value:
        type: https://errors.lerian.studio/v1/MTCH-0303
        title: Bad Request
        status: 400
        detail: The format field is required for .xml uploads and must be sent before the file part; reorder the multipart fields and try again
        code: MTCH-0303
    mtch-0304-file-is-empty:
      summary: File is empty
      value:
        type: https://errors.lerian.studio/v1/MTCH-0304
        title: Bad Request
        status: 400
        detail: The uploaded file is empty; no import job was created. Upload a file with at least one row and try again.
        code: MTCH-0304
    mtch-0301-source-not-found:
      summary: Source not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0301
        title: Not Found
        status: 404
        detail: The source could not be found; no job was created and nothing from this upload was imported. Check the source id and try again.
        code: MTCH-0301
    mtch-0302-field-mapping-not-found-for-source:
      summary: Field mapping not found for source
      value:
        type: https://errors.lerian.studio/v1/MTCH-0302
        title: Not Found
        status: 404
        detail: No field mapping is configured for this source; no job was created and nothing from this upload was imported. Configure a field mapping for the source and try again.
        code: MTCH-0302
    mtch-0311-upload-stalled-no-bytes-received-for-1m0s-the-import-was-fai:
      summary: 'Upload stalled: no bytes received for 1m0s; the import was failed'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0311
        title: Request Timeout
        status: 408
        detail: 'The upload stalled: no data arrived for longer than the allowed idle window, so the import was stopped and marked failed. Check the network connection and upload the file again.'
        code: MTCH-0311
    mtch-0010-upload-exceeds-the-configured-limit-of-1073741824-bytes-inge:
      summary: Upload exceeds the configured limit
      value:
        type: https://errors.lerian.studio/v1/MTCH-0010
        title: Request Entity Too Large
        status: 413
        detail: The upload is larger than the 1073741824-byte limit configured for this deployment; nothing was imported. Split the file into smaller uploads, or ask an administrator to raise the limit, then try again.
        code: MTCH-0010
    mtch-0309-error-rate-policy-exceeded-200-of-1000-rows-failed-exceeding:
      summary: 'Error rate policy exceeded: 200 of 1000 rows failed, exceeding the...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0309
        title: Unprocessable Entity
        status: 422
        detail: the upload exceeded its configured error-rate policy (200 of 1000 rows failed, exceeding the error-rate limit configured on this source (10%)); the import was stopped and marked failed, and matcher makes a best-effort attempt to remove the rows it already wrote from reconciliation. Correct the source file or raise the error-rate limit on this source, then re-upload.
        code: MTCH-0309
    mtch-0307-preview-file-document-parsed-but-no-elements-matched-the-exp:
      summary: 'Preview file: document parsed but no elements matched the expected record...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0307
        title: Bad Request
        status: 400
        detail: The XML document parsed but contained no recognized transaction records; check the file structure or choose a different preview format
        code: MTCH-0307
    400-reason-is-required:
      summary: Reason is required
      value:
        title: Bad Request
        status: 400
        detail: reason is required
    mtch-0005-transaction-not-found:
      summary: Transaction not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The transaction could not be found. Check the transaction id and try again.
        code: MTCH-0005
    mtch-0305-transaction-cannot-be-ignored-only-unmatched-transactions-ca:
      summary: 'Transaction cannot be ignored: only UNMATCHED transactions can be ignored'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0305
        title: Conflict
        status: 409
        detail: 'transaction cannot be ignored: only UNMATCHED transactions can be ignored'
        code: MTCH-0305
    400-invalid-search-parameters:
      summary: Invalid search parameters
      value:
        title: Bad Request
        status: 400
        detail: One or more search filters are invalid. Check the amount range, date range, and source id, then try again.
    400-invalid-amount-format:
      summary: Invalid amount format
      value:
        title: Bad Request
        status: 400
        detail: The amount is not a valid decimal number; no adjustment was created. Provide a valid decimal amount and try again.
    mtch-0401-no-sources-configured-for-context:
      summary: No sources configured for context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0401
        title: Bad Request
        status: 400
        detail: This context has no sources configured; no match run was created for this request. Add at least two sources to the context, then run the match again.
        code: MTCH-0401
    mtch-0402-at-least-two-sources-are-required:
      summary: At least two sources are required
      value:
        type: https://errors.lerian.studio/v1/MTCH-0402
        title: Bad Request
        status: 400
        detail: at least two sources are required
        code: MTCH-0402
    mtch-0404-1-1-contexts-require-exactly-one-source-per-side:
      summary: 1:1 contexts require exactly one source per side
      value:
        type: https://errors.lerian.studio/v1/MTCH-0404
        title: Bad Request
        status: 400
        detail: 1:1 contexts require exactly one source per side
        code: MTCH-0404
    mtch-0408-another-match-run-is-already-in-progress-for-this-context:
      summary: Another match run is already in progress for this context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0408
        title: Conflict
        status: 409
        detail: Another match run is already in progress for this context; no match run was created for this request. Wait for the current run to finish, then retry.
        code: MTCH-0408
    mtch-0406-fee-normalization-is-enabled-but-no-fee-rules-are-configured:
      summary: Fee normalization is enabled but no fee rules are configured for this context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0406
        title: Unprocessable Entity
        status: 422
        detail: fee normalization is enabled but no fee rules are configured for this context
        code: MTCH-0406
    mtch-0407-fee-rules-are-misconfigured-for-this-context:
      summary: Fee rules are misconfigured for this context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0407
        title: Unprocessable Entity
        status: 422
        detail: This context's fee rules are misconfigured (too many fee rules, or a rule references a fee schedule that no longer exists); no match run was created for this request. Ask an administrator to check the context's fee rule configuration.
        code: MTCH-0407
    mtch-0005-match-group-not-found:
      summary: Match group not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The match group could not be found; this un-match was not applied. Check the match group id and try again.
        code: MTCH-0005
    400-duplicate-transaction-ids-provided:
      summary: Duplicate transaction IDs provided
      value:
        title: Bad Request
        status: 400
        detail: duplicate transaction IDs provided
    mtch-0005-one-or-more-transactions-not-found:
      summary: One or more transactions not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: One or more of the submitted transaction ids do not exist in this context. No match was created; check the ids and try again.
        code: MTCH-0005
    mtch-0005-match-run-not-found:
      summary: Match run not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The match run could not be found; check the run id and try again
        code: MTCH-0005
    400-invalid-date-range:
      summary: Invalid date range
      value:
        title: Bad Request
        status: 400
        detail: date_from and date_to must each be a valid YYYY-MM-DD date, and date_from must not be after date_to
    mtch-0201-connection-not-found:
      summary: Connection not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0201
        title: Not Found
        status: 404
        detail: No connection matches this id. Check the connection id and try again.
        code: MTCH-0201
    mtch-0204-invalid-extraction-request-start-date-must-use-yyyy-mm-dd-fo:
      summary: 'Invalid extraction request: start date must use YYYY-MM-DD format'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0204
        title: Bad Request
        status: 400
        detail: 'the extraction request is invalid: start date must use YYYY-MM-DD format'
        code: MTCH-0204
    mtch-0202-extraction-not-found:
      summary: Extraction not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0202
        title: Not Found
        status: 404
        detail: No extraction request matches this id. Check the extraction id and try again.
        code: MTCH-0202
    mtch-0205-discovery-refresh-already-in-progress:
      summary: Discovery refresh already in progress
      value:
        type: https://errors.lerian.studio/v1/MTCH-0205
        title: Conflict
        status: 409
        detail: A discovery refresh is already running for this deployment; this request was not started. Wait for it to finish and try again.
        code: MTCH-0205
    400-invalid-dueat-format-expected-rfc3339:
      summary: Invalid dueAt format, expected RFC3339
      value:
        title: Bad Request
        status: 400
        detail: invalid dueAt format, expected RFC3339
    404-not-found:
      summary: Not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: This callback token is not valid; ask an administrator to check the callback credential configured for this integration
        code: MTCH-0005
    404-no-detail:
      summary: Not Found
      value:
        title: Not Found
        status: 404
    mtch-0504-callback-is-already-being-processed:
      summary: Callback is already being processed
      value:
        type: https://errors.lerian.studio/v1/MTCH-0504
        title: Conflict
        status: 409
        detail: Another callback for this idempotency key is still being processed; this attempt was not processed. Retry the request in a moment; if it keeps failing, contact support.
        code: MTCH-0504
    mtch-0505-callback-can-be-retried:
      summary: Callback can be retried
      value:
        type: https://errors.lerian.studio/v1/MTCH-0505
        title: Conflict
        status: 409
        detail: The callback's processing status could not be confirmed; this attempt was not processed. Retry the request in a moment; if it keeps failing, contact support.
        code: MTCH-0505
    mtch-0506-callback-rate-limit-exceeded:
      summary: Callback rate limit exceeded
      value:
        type: https://errors.lerian.studio/v1/MTCH-0506
        title: Too Many Requests
        status: 429
        detail: This external system has exceeded its callback rate limit; this callback was not processed. Retry the request in a moment; if it keeps failing, contact support.
        code: MTCH-0506
    503-internal-error:
      summary: Service Unavailable
      value:
        title: Service Unavailable
        status: 503
        detail: internal error
    mtch-0208-connector-type-is-not-registered-db2:
      summary: 'Connector type is not registered: "DB2"'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0208
        title: Bad Request
        status: 400
        detail: The requested connector type is not registered on this deployment; use one of the registered connector types
        code: MTCH-0208
    mtch-0203-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0203
        title: Service Unavailable
        status: 503
        detail: Source connectivity is temporarily unavailable; retry the request, then ask an administrator to check the discovery service if the failure continues.
        code: MTCH-0203
    mtch-0001-rest-credential-field-is-required:
      summary: Required credential field missing
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: This connector type requires a credential field that the request does not supply; no connection was created. Supply every credential field this connector type requires and try again.
        code: MTCH-0001
        errors:
          - location: credential.apiKey
            message: this credential field is required for the requested connector type
    400-at-least-one-connection-field-must-be-provided:
      summary: At least one connection field must be provided
      value:
        title: Bad Request
        status: 400
        detail: at least one connection field must be provided
    mtch-0103-cannot-archive-context-in-archived-status-invalid-state-tran:
      summary: 'Cannot archive context in ARCHIVED status: invalid state transition'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0103
        title: Conflict
        status: 409
        detail: This context is already archived; nothing was archived. Reload the context to see its current status.
        code: MTCH-0103
    mtch-0103-cannot-unarchive-context-in-active-status-invalid-state-tran:
      summary: 'Cannot unarchive context in ACTIVE status: invalid state transition'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0103
        title: Conflict
        status: 409
        detail: Only an archived context can be restored, and this context is not archived; nothing was restored. Reload the context to see its current status.
        code: MTCH-0103
    400-invalid-source-binding-payload:
      summary: Invalid source binding payload
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: "The source binding's rail-specific settings don't match its kind: a file binding needs transport config and no connection id; a query binding needs a connection id and no transport config. No binding was created; correct the payload and try again."
        code: MTCH-0001
    mtch-0005-source-binding-not-found:
      summary: Source binding not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The source binding could not be found; check the binding id and try again.
        code: MTCH-0005
    mtch-0007-aggregator-connection-already-exists:
      summary: Aggregator connection already exists
      value:
        type: https://errors.lerian.studio/v1/MTCH-0007
        title: Conflict
        status: 409
        detail: An aggregator connection with this config name already exists; nothing was created. Choose a different config name and try again.
        code: MTCH-0007
    mtch-0005-aggregator-connection-not-found:
      summary: Aggregator connection not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The aggregator connection could not be found; check the connection id and try again
        code: MTCH-0005
    mtch-0213-consent-flow-not-available:
      summary: Consent flow not available for this vendor
      value:
        type: https://errors.lerian.studio/v1/MTCH-0213
        title: Unprocessable Entity
        status: 422
        detail: Matcher cannot open a hosted consent flow for this aggregator vendor on this deployment, so no consent token was created and nothing changed. Contact support if you need the consent flow for this vendor.
        code: MTCH-0213
    mtch-0212-consent-token-not-issued:
      summary: Vendor did not issue a consent token
      value:
        type: https://errors.lerian.studio/v1/MTCH-0212
        title: Unprocessable Entity
        status: 422
        detail: The aggregator vendor did not issue a consent token, so nothing was created and nothing changed. Test the connection's credentials and try again; if they are healthy, retry shortly.
        code: MTCH-0212
    400-clientid-and-secret-must-both-be-supplied-to-rotate-the-cred:
      summary: clientId and secret must both be supplied to rotate the credential, or both...
      value:
        title: Bad Request
        status: 400
        detail: clientId and secret must both be supplied to rotate the credential, or both omitted to keep it
    400-connection-config-name-is-required:
      summary: Connection_config_name is required
      value:
        title: Bad Request
        status: 400
        detail: connection_config_name is required
    mtch-0201-no-aggregator-connection-for-the-given-config-name:
      summary: No aggregator connection for the given config name
      value:
        type: https://errors.lerian.studio/v1/MTCH-0201
        title: Not Found
        status: 404
        detail: No aggregator connection exists for this config name. Create the connection first, then retry.
        code: MTCH-0201
    400-bad-request:
      summary: Bad Request
      value:
        title: Bad Request
        status: 400
    401-unauthorized:
      summary: Unauthorized
      value:
        title: Unauthorized
        status: 401
    413-request-body-is-too-large-limit-10485760-bytes:
      summary: Request body is too large
      value:
        title: Request Entity Too Large
        status: 413
        detail: request body is too large limit=10485760 bytes
    415-evidence-file-content-type-is-not-supported:
      summary: Evidence file content type is not supported
      value:
        title: Unsupported Media Type
        status: 415
        detail: Evidence files must be a PDF, PNG, JPEG or CSV, and this one is not; nothing was attached to this dispute. Convert the file to a supported format and upload it again.
    mtch-0005-callback-credential-not-found:
      summary: Callback credential not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No callback credential matches this id for your tenant; the change was not applied. Check the credential id and try again.
        code: MTCH-0005
    400-assignee-is-required-for-bulk-assign:
      summary: Assignee is required for bulk assign
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: An assignee is required to assign this exception.
        code: MTCH-0001
    mtch-0503-exception-cannot-transition-in-current-state:
      summary: Exception cannot transition in current state
      value:
        type: https://errors.lerian.studio/v1/MTCH-0503
        title: Unprocessable Entity
        status: 422
        detail: This exception's current status does not allow the requested assign or resolve action; nothing was changed. Reload the exception to see its current status, then retry a valid action.
        code: MTCH-0503
    400-resolution-is-required-for-bulk-resolve:
      summary: Resolution is required for bulk resolve
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: A resolution is required to resolve this exception.
        code: MTCH-0001
    mtch-0005-extraction-review-not-found:
      summary: Extraction review not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The extraction review could not be found; check the review id and try again.
        code: MTCH-0005
    mtch-0324-invalid-extraction-review-status-transition-cannot-approve-f:
      summary: 'Invalid extraction review status transition: cannot approve from APPROVED'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0324
        title: Conflict
        status: 409
        detail: 'this extraction review cannot make that status change: cannot approve from APPROVED'
        code: MTCH-0324
    mtch-0324-persist-approved-review-update-extraction-review-extraction:
      summary: 'Persist approved review: update extraction review: extraction review changed...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0324
        title: Conflict
        status: 409
        detail: This extraction review changed concurrently, and matcher cannot tell from here whether your approval or rejection already took effect; reload the review to see its current status, and only resubmit while it still shows PENDING_REVIEW
        code: MTCH-0324
    mtch-0324-invalid-extraction-review-status-transition-cannot-reject-fr:
      summary: 'Invalid extraction review status transition: cannot reject from REJECTED'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0324
        title: Conflict
        status: 409
        detail: 'this extraction review cannot make that status change: cannot reject from REJECTED'
        code: MTCH-0324
    mtch-0324-persist-rejected-review-update-extraction-review-extraction:
      summary: 'Persist rejected review: update extraction review: extraction review changed...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0324
        title: Conflict
        status: 409
        detail: This extraction review changed concurrently, and matcher cannot tell from here whether your approval or rejection already took effect; reload the review to see its current status, and only resubmit while it still shows PENDING_REVIEW
        code: MTCH-0324
    mtch-0319-document-extraction-is-not-enabled-for-this-tenant:
      summary: Document extraction consent not granted
      value:
        type: https://errors.lerian.studio/v1/MTCH-0319
        title: Forbidden
        status: 403
        detail: document extraction consent has not been granted on this deployment
        code: MTCH-0319
    mtch-0321-no-transaction-candidates-could-be-extracted-from-the-docume:
      summary: No transaction candidates could be extracted from the document
      value:
        type: https://errors.lerian.studio/v1/MTCH-0321
        title: Unprocessable Entity
        status: 422
        detail: No transaction candidates could be extracted from this document, so no extraction review was created. Check that the document is a supported format with readable transaction data, then upload it again.
        code: MTCH-0321
    mtch-0318-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0318
        title: Service Unavailable
        status: 503
        detail: Document extraction is not configured on this deployment; ingest the document data manually or ask an administrator to enable document extraction.
        code: MTCH-0318
    mtch-0320-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0320
        title: Service Unavailable
        status: 503
        detail: The document extractor is temporarily unavailable; ingest the document data manually or retry after the extractor recovers.
        code: MTCH-0320
    mtch-0314-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0314
        title: Service Unavailable
        status: 503
        detail: The configured source could not be reached or read; check the source connection and credentials, then retry the fetch.
        code: MTCH-0314
    mtch-0315-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0315
        title: Service Unavailable
        status: 503
        detail: Automatic mapping proposals are not configured on this deployment; create the field map manually or ask an administrator to enable mapping proposals.
        code: MTCH-0315
    mtch-0316-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0316
        title: Service Unavailable
        status: 503
        detail: The mapping advisor could not produce a proposal; create the field map manually or retry after the advisor recovers.
        code: MTCH-0316
    400-invalid-layout-template:
      summary: Invalid layout template
      value:
        title: Bad Request
        status: 400
        detail: The layout template definition is invalid (a malformed descriptor, record, or field); nothing was created. Correct the layout and try again.
    mtch-0007-layout-template-already-exists-for-this-format:
      summary: Layout template already exists for this format
      value:
        type: https://errors.lerian.studio/v1/MTCH-0007
        title: Conflict
        status: 409
        detail: A layout template already uses this format key; nothing was created. Choose a different format key, or update the existing template instead.
        code: MTCH-0007
    mtch-0006-layout-template-validation-catalog-field-overruns-record-wid:
      summary: 'Layout template validation: catalog field overruns record width: variant...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0006
        title: Unprocessable Entity
        status: 422
        detail: 'The layout template did not pass validation: its fields overlap, run past the record width, leave a required field unmapped, or define a record with no fields. Nothing was created. Correct the layout and submit it again.'
        code: MTCH-0006
    mtch-0005-layout-template-not-found:
      summary: Layout template not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No active layout template matches this id. Check the layout template id and try again.
        code: MTCH-0005
    400-transaction-id-is-required:
      summary: Transaction id is required
      value:
        title: Bad Request
        status: 400
        detail: A target transaction id is required to list match candidates.
    mtch-0005-target-transaction-not-found-in-context:
      summary: Target transaction not found in context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The target transaction was not found in this context; check the transaction id.
        code: MTCH-0005
    mtch-0005-reconciliation-context-not-found:
      summary: Reconciliation context not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No reconciliation context matches this id; check the context id and try again.
        code: MTCH-0005
    mtch-0410-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0410
        title: Service Unavailable
        status: 503
        detail: Rule suggestions are not configured on this deployment; author match rules manually or ask an administrator to enable rule suggestions.
        code: MTCH-0410
    mtch-0409-rule-suggestion-is-not-enabled-for-this-tenant:
      summary: Rule suggestion consent not granted
      value:
        type: https://errors.lerian.studio/v1/MTCH-0409
        title: Forbidden
        status: 403
        detail: rule suggestion consent has not been granted on this deployment
        code: MTCH-0409
    mtch-0411-internal-error:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0411
        title: Service Unavailable
        status: 503
        detail: The rule advisor could not produce suggestions; author match rules manually or retry after the advisor recovers.
        code: MTCH-0411
    mtch-0005-rule-suggestion-not-found:
      summary: Rule suggestion not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The rule suggestion could not be found; the decision was not applied. Check the suggestion id and try again.
        code: MTCH-0005
    mtch-0413-approving-rule-suggestion-invalid-rule-suggestion-review-sta:
      summary: 'Approving rule suggestion: invalid rule suggestion review status transition:...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0413
        title: Conflict
        status: 409
        detail: This rule suggestion cannot move to the requested status from its current status; the decision was not applied. Refresh the suggestion and retry a valid transition.
        code: MTCH-0413
    mtch-0413-persisting-approved-review-update-rule-suggestion-review-rul:
      summary: 'Persisting approved review: update rule suggestion review: rule suggestion...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0413
        title: Conflict
        status: 409
        detail: This rule suggestion was changed by another request just now; the decision was not applied. Refresh the suggestion and retry.
        code: MTCH-0413
    mtch-0413-rejecting-rule-suggestion-invalid-rule-suggestion-review-sta:
      summary: 'Rejecting rule suggestion: invalid rule suggestion review status transition:...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0413
        title: Conflict
        status: 409
        detail: This rule suggestion cannot move to the requested status from its current status; the decision was not applied. Refresh the suggestion and retry a valid transition.
        code: MTCH-0413
    mtch-0413-persisting-rejected-review-update-rule-suggestion-review-rul:
      summary: 'Persisting rejected review: update rule suggestion review: rule suggestion...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0413
        title: Conflict
        status: 409
        detail: This rule suggestion was changed by another request just now; the decision was not applied. Refresh the suggestion and retry.
        code: MTCH-0413
    400-specify-either-a-rule-id-or-an-inline-rule-definition-not-bo:
      summary: Specify either a rule id or an inline rule definition, not both
      value:
        title: Bad Request
        status: 400
        detail: A simulation takes either a saved rule id or an inline rule definition, not both; the simulation was not run. Send only one of them and try again.
    404-match-rule-not-found-in-context:
      summary: Match rule not found in context
      value:
        title: Not Found
        status: 404
        detail: The match rule could not be found in this context; check the rule id and try again
    404-reconciliation-context-not-found:
      summary: Reconciliation context not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No reconciliation context matches this id; check the context id and try again.
        code: MTCH-0005
    mtch-0412-the-approved-suggestion-failed-validation:
      summary: The approved suggestion failed validation
      value:
        type: https://errors.lerian.studio/v1/MTCH-0412
        title: Unprocessable Entity
        status: 422
        detail: This suggestion failed validation and cannot be approved; the decision was not applied. Reject it and create the match rule manually instead.
        code: MTCH-0412
    400-invalid-pagination-parameters--get-v1-matching-contexts-contextid-open-items:
      summary: Invalid pagination parameters
      value:
        title: Bad Request
        status: 400
        detail: The pagination cursor could not be decoded; omit it to start from the first page, or use the exact cursor value returned by a previous response
    400-invalid-pagination-parameters--get-v1-matching-contexts-contextid-adjustments:
      summary: Invalid pagination parameters
      value:
        title: Bad Request
        status: 400
        detail: The pagination cursor could not be decoded; omit it to start from the first page, or use the exact cursor value returned by a previous response
    400-invalid-pagination-parameters--get-v1-matching-contexts-contextid-runs:
      summary: Invalid pagination parameters
      value:
        title: Bad Request
        status: 400
        detail: The pagination cursor could not be decoded; omit it to start from the first page, or use the exact cursor value returned by a previous response
    400-invalid-pagination-parameters--get-v1-matching-runs-runid-groups:
      summary: Invalid pagination parameters
      value:
        title: Bad Request
        status: 400
        detail: The pagination cursor could not be decoded; omit it to start from the first page, or use the exact cursor value returned by a previous response
    400-invalid-match-rule-payload--patch-v1-contexts-contextid-rules-ruleid:
      summary: Invalid match rule payload
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The match rule's config is invalid; the update was not applied. Fix the config and try again.
        code: MTCH-0001
    400-invalid-filter-parameters--get-v1-disputes:
      summary: Invalid filter parameters
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: The date range is invalid. Correct the filter value and try again.
        code: MTCH-0001
    400-invalid-exception-id--post-v1-exceptions-bulk-resolve:
      summary: Invalid exception id
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: One or more ids in this request are not valid exception ids; no exceptions were resolved. Check the exception ids and try again.
        code: MTCH-0001
    400-invalid-exception-id--post-v1-exceptions-bulk-dispatch:
      summary: Invalid exception id
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: One or more ids in this request are not valid exception ids; no exceptions were dispatched. Check the exception ids and try again.
        code: MTCH-0001
    400-invalid-source-binding-payload--patch-v1-contexts-contextid-sources-sourceid-bindings-bindingid:
      summary: Invalid source binding payload
      value:
        type: https://errors.lerian.studio/v1/MTCH-0001
        title: Bad Request
        status: 400
        detail: 'The source binding payload is invalid: format and schedule must each be a non-empty value. The update was not applied; correct the payload and try again.'
        code: MTCH-0001
    mtch-0005-aggregator-connection-not-found--post-v1-discovery-aggregator-connections-test:
      summary: Aggregator connection not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No aggregator connection with that name exists, so nothing was tested. Check the name against your aggregator connections list and try again.
        code: MTCH-0005
    400-invalid-layout-template--put-v1-imports-formats-templates-templateid:
      summary: Invalid layout template
      value:
        title: Bad Request
        status: 400
        detail: The layout template definition is invalid (a malformed descriptor, record, or field); the stored template was not changed. Correct the layout and try again.
    mtch-0101-a-reconciliation-context-with-this-name-already-exists--patch-v1-contexts-contextid:
      summary: A reconciliation context with this name already exists
      value:
        type: https://errors.lerian.studio/v1/MTCH-0101
        title: Conflict
        status: 409
        detail: A reconciliation context with this name already exists; the update was not applied. Choose a different name.
        code: MTCH-0101
    mtch-0102-priority-already-exists-in-context--post-v1-contexts:
      summary: Priority already exists in context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0102
        title: Conflict
        status: 409
        detail: This match rule's priority is already used by another rule in this context; the context was not created. Choose a different priority for each rule.
        code: MTCH-0102
    mtch-0102-priority-already-exists-in-context--patch-v1-contexts-contextid-rules-ruleid:
      summary: Priority already exists in context
      value:
        type: https://errors.lerian.studio/v1/MTCH-0102
        title: Conflict
        status: 409
        detail: This priority is already used by another match rule in this context; the update was not applied. Choose a different priority.
        code: MTCH-0102
    mtch-0113-match-rule-not-found--patch-v1-contexts-contextid-rules-ruleid:
      summary: Match rule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0113
        title: Not Found
        status: 404
        detail: No match rule matches this id in this context; the update was not applied. Check the match rule id and try again.
        code: MTCH-0113
    mtch-0113-match-rule-not-found--delete-v1-contexts-contextid-rules-ruleid:
      summary: Match rule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0113
        title: Not Found
        status: 404
        detail: No match rule matches this id in this context; nothing was deleted. Check the match rule id and try again.
        code: MTCH-0113
    mtch-0113-match-rule-not-found--post-v1-contexts-contextid-rules-reorder:
      summary: Match rule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0113
        title: Not Found
        status: 404
        detail: One or more rule ids in the reorder list do not match a match rule in this context, or the list repeats an id; the reorder was not applied. Check the rule ids and try again.
        code: MTCH-0113
    mtch-0111-source-not-found--patch-v1-contexts-contextid-sources-sourceid:
      summary: Source not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0111
        title: Not Found
        status: 404
        detail: The source could not be found; no changes were saved. Check the source id and try again.
        code: MTCH-0111
    mtch-0111-source-not-found--post-v1-contexts-contextid-sources-sourceid-archive:
      summary: Source not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0111
        title: Not Found
        status: 404
        detail: The source could not be found; nothing was archived. Check the source id and try again.
        code: MTCH-0111
    mtch-0111-source-not-found--post-v1-contexts-contextid-sources-sourceid-restore:
      summary: Source not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0111
        title: Not Found
        status: 404
        detail: The source could not be found; nothing was restored. Check the source id and try again.
        code: MTCH-0111
    mtch-0111-source-not-found--post-v1-contexts-contextid-sources-sourceid-bindings:
      summary: Source not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0111
        title: Not Found
        status: 404
        detail: The source could not be found; no changes were applied. Check the source id and try again.
        code: MTCH-0111
    mtch-0111-source-not-found--patch-v1-contexts-contextid-sources-sourceid-bindings-bindingid:
      summary: Source not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0111
        title: Not Found
        status: 404
        detail: The source could not be found; no changes were applied. Check the source id and try again.
        code: MTCH-0111
    mtch-0111-source-not-found--delete-v1-contexts-contextid-sources-sourceid-bindings-bindingid:
      summary: Source not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0111
        title: Not Found
        status: 404
        detail: The source could not be found; no changes were applied. Check the source id and try again.
        code: MTCH-0111
    mtch-0111-source-not-found--post-v1-contexts-contextid-sources-sourceid-field-maps:
      summary: Source not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0111
        title: Not Found
        status: 404
        detail: The source could not be found; no changes were applied. Check the source id and try again.
        code: MTCH-0111
    mtch-0112-field-map-not-found--get-v1-contexts-contextid-sources-sourceid-field-maps:
      summary: Field map not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0112
        title: Not Found
        status: 404
        detail: No field map is configured for this source yet; create one to import file formats that need column mapping (not required for camt053 sources)
        code: MTCH-0112
    mtch-0115-fee-schedule-not-found--patch-v1-fee-schedules-scheduleid:
      summary: Fee schedule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0115
        title: Not Found
        status: 404
        detail: The fee schedule could not be found; no changes were saved. Check the fee schedule id and try again.
        code: MTCH-0115
    mtch-0115-fee-schedule-not-found--delete-v1-fee-schedules-scheduleid:
      summary: Fee schedule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0115
        title: Not Found
        status: 404
        detail: The fee schedule could not be found; nothing was deleted. Check the fee schedule id and try again.
        code: MTCH-0115
    mtch-0116-schedule-not-found--patch-v1-contexts-contextid-schedules-scheduleid:
      summary: Schedule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0116
        title: Not Found
        status: 404
        detail: No reconciliation schedule matches this id; the update was not applied. Check the schedule id and try again.
        code: MTCH-0116
    mtch-0116-schedule-not-found--delete-v1-contexts-contextid-schedules-scheduleid:
      summary: Schedule not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0116
        title: Not Found
        status: 404
        detail: No reconciliation schedule matches this id; nothing was deleted. Check the schedule id and try again.
        code: MTCH-0116
    mtch-0008-internal-error--post-v1-contexts-contextid-export-jobs:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0702
        title: Service Unavailable
        status: 503
        detail: Export processing is disabled on this deployment; ask an administrator to enable exports.
        code: MTCH-0702
    400-validation-failed--post-v1-imports-contexts-contextid-sources-sourceid-extract-document:
      summary: Validation failed
      value:
        title: Bad Request
        status: 400
        detail: validation failed
    mtch-0005-actor-mapping-not-found--post-v1-governance-actor-mappings-actorid-pseudonymize:
      summary: Actor mapping not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The actor mapping could not be found; no fields were redacted. Check the actor id and try again.
        code: MTCH-0005
    mtch-0005-actor-mapping-not-found--delete-v1-governance-actor-mappings-actorid:
      summary: Actor mapping not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The actor mapping could not be found; nothing was deleted. Check the actor id and try again.
        code: MTCH-0005
    400-file-is-required--post-v1-imports-contexts-contextid-sources-sourceid-preview:
      summary: File is required
      value:
        title: Bad Request
        status: 400
        detail: file is required
    mtch-0005-transaction-not-found--post-v1-matching-adjustments:
      summary: Transaction not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No transaction matches this id in this context; no adjustment was created. Check the transaction id and try again.
        code: MTCH-0005
    503-internal-error--post-v1-discovery-webhooks-provider-webhooktoken:
      summary: Service Unavailable
      value:
        type: https://errors.lerian.studio/v1/MTCH-0008
        title: Service Unavailable
        status: 503
        detail: internal error
        code: MTCH-0008
    mtch-0005-source-binding-not-found--patch-v1-contexts-contextid-sources-sourceid-bindings-bindingid:
      summary: Source binding not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The source binding could not be found; the update was not applied. Check the binding id and try again.
        code: MTCH-0005
    mtch-0005-source-binding-not-found--delete-v1-contexts-contextid-sources-sourceid-bindings-bindingid:
      summary: Source binding not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The source binding could not be found; nothing was deleted. Check the binding id and try again.
        code: MTCH-0005
    mtch-0005-extraction-review-not-found--post-v1-imports-contexts-contextid-extraction-reviews-reviewid-approve:
      summary: Extraction review not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The extraction review could not be found; nothing was applied. Check the review id and try again.
        code: MTCH-0005
    mtch-0005-extraction-review-not-found--post-v1-imports-contexts-contextid-extraction-reviews-reviewid-reject:
      summary: Extraction review not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: The extraction review could not be found; nothing was applied. Check the review id and try again.
        code: MTCH-0005
    mtch-0007-layout-template-already-exists-for-this-format--put-v1-imports-formats-templates-templateid:
      summary: Layout template already exists for this format
      value:
        type: https://errors.lerian.studio/v1/MTCH-0007
        title: Conflict
        status: 409
        detail: Another layout template already uses this format key; the update was not applied. Choose a different format key and try again.
        code: MTCH-0007
    mtch-0006-layout-template-validation-catalog-field-overruns-record-wid--put-v1-imports-formats-templates-templateid:
      summary: 'Layout template validation: catalog field overruns record width: variant...'
      value:
        type: https://errors.lerian.studio/v1/MTCH-0006
        title: Unprocessable Entity
        status: 422
        detail: 'The replacement layout did not pass validation: its fields overlap, run past the record width, leave a required field unmapped, or define a record with no fields. The stored template was not changed. Correct the layout and try again.'
        code: MTCH-0006
    mtch-0005-layout-template-not-found--delete-v1-imports-formats-templates-templateid:
      summary: Layout template not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No active layout template matches this id; nothing was deleted. Check the layout template id and try again.
        code: MTCH-0005
    mtch-0005-layout-template-not-found--put-v1-imports-formats-templates-templateid:
      summary: Layout template not found
      value:
        type: https://errors.lerian.studio/v1/MTCH-0005
        title: Not Found
        status: 404
        detail: No active layout template matches this id; the update was not applied. Check the layout template id and try again.
        code: MTCH-0005
    mtch-0103-context-is-not-ready-for-activation:
      summary: Context is not ready for activation
      value:
        type: https://errors.lerian.studio/v1/MTCH-0103
        title: Conflict
        status: 409
        detail: context is not ready for activation; call GET setup-progress for the missing requirements
        errors:
          - location: context.activation.requirement.right-source
          - location: context.activation.requirement.match-rule
        code: MTCH-0103