@lerianstudio/matcher-mcp 5.0.0-beta.8 → 5.0.0-beta.80

package/dist/spec/openapi.yaml

@@ -184,6 +184,9 @@ components:
           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
@@ -209,6 +212,12 @@ components:
           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
@@ -230,6 +239,33 @@ components:
         - createdAt
         - updatedAt
       type: object
+    AdminAssignPlanInputBody:
+      additionalProperties: false
+      properties:
+        plan:
+          description: "The plan code to assign. ONLY \"enterprise\" is accepted: self-serve plans are bought through checkout and converged from the live subscription's price, so assigning one here would be a payment-processor bypass the next processor delivery silently reverts. Any other code is refused with 409."
+          maxLength: 64
+          type: string
+      required:
+        - plan
+      type: object
+    AdminAssignPlanResult:
+      additionalProperties: false
+      properties:
+        billingStatus:
+          description: The commercial standing the workspace now holds. An enterprise contract is in good standing the moment it is signed, so this is always "active".
+          type: string
+        plan:
+          description: The plan the workspace now holds.
+          type: string
+        slug:
+          description: The workspace assigned.
+          type: string
+      required:
+        - slug
+        - plan
+        - billingStatus
+      type: object
     AdminWorkspaceBilling:
       additionalProperties: false
       properties:
@@ -321,10 +357,15 @@ components:
       additionalProperties: false
       properties:
         accountRef:
-          description: Stored opaque vendor account reference (Pluggy itemId, Belvo link id)
+          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:
@@ -342,7 +383,7 @@ components:
             - a1b2c3d4-5678-90ab-cdef-1234567890ab
           type: string
         testable:
-          description: Whether Matcher can run a connectivity test for this connection's aggregator vendor
+          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
@@ -361,6 +402,7 @@ components:
         - baseUrl
         - accountRef
         - testable
+        - awaitingConsent
       type: object
     AggregatorConnectionListResponse:
       additionalProperties: false
@@ -400,10 +442,9 @@ components:
       additionalProperties: false
       properties:
         accountRef:
-          description: Opaque vendor account reference (Pluggy itemId, Belvo link id) the webhook pull threads onto its request
+          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
-          minLength: 1
           type: string
         baseUrl:
           description: Vendor API base URL, stored as the connection host
@@ -438,7 +479,6 @@ components:
         - vendor
         - configName
         - baseUrl
-        - accountRef
         - clientId
         - secret
       type: object
@@ -446,10 +486,15 @@ components:
       additionalProperties: false
       properties:
         accountRef:
-          description: Stored opaque vendor account reference (Pluggy itemId, Belvo link id)
+          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:
@@ -474,6 +519,52 @@ components:
         - 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: Short-lived, widget-ready consent token. Returned exactly once and never stored — pass it to the vendor widget and discard it.
+          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
@@ -638,6 +729,12 @@ components:
             - 0
           format: int64
           type: integer
+        fromSeq:
+          description: "Effective verification floor: the first tenant_seq eligible for inspection (1 when fromSeq was omitted). Resume a truncated run at fromSeq + verifiedCount"
+          examples:
+            - 1
+          format: int64
+          type: integer
         intact:
           description: True when every inspected record links to the previous one and matches its stored hash
           examples:
@@ -656,6 +753,7 @@ components:
           type: integer
       required:
         - intact
+        - fromSeq
         - verifiedCount
         - truncated
       type: object
@@ -884,6 +982,11 @@ components:
     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:
@@ -932,7 +1035,15 @@ components:
       additionalProperties: false
       properties:
         canonicalKey:
-          description: Canonical field-map key (e.g. amount, external_id, currency, date)
+          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
@@ -1002,6 +1113,11 @@ components:
           type: string
         ruleType:
           description: Strategy of the rule that produced the best score
+          enum:
+            - EXACT
+            - TOLERANCE
+            - DATE_LAG
+            - FUZZY
           examples:
             - EXACT
           type: string
@@ -1060,6 +1176,9 @@ components:
             - "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
@@ -1801,7 +1920,91 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: "Source-specific configuration object (connection and parsing settings). Optional; defaults to an empty object when omitted. Reserved key duplicate_key: the ordered list of mapped fields that make two rows the same row — any of external_id, amount, currency, date, description, fee_amount, fee_currency. Omit it and rows are deduplicated on external_id alone. A field this source's field map does not fill is refused, because a key over a field that is always empty 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: the aggregator retracts a movement by naming its external id, so that id has to stay this source's row identity. A config holding both is refused in either direction — drop duplicate_key from a bound source, or disconnect the aggregator connection first. Reserved read-only key duplicate_key_changed_at: the RFC 3339 moment duplicate-key detection last changed meaning on this source, set by the server; a value sent by a client is discarded. It moves for either change that re-keys future rows — editing duplicate_key, or the field map remapping the column a declared field reads (a source keyed on description whose description column moves derives a different key for the same movement). Reserved key duplicate_policy: what happens to a row repeating the duplicate key — FLAG_AS_EXCEPTION (the default: the repeat is kept out of the import and raised as a duplicate exception on the row it repeated), KEEP_FIRST (the repeat is dropped and nothing is raised), or REJECT (the repeat is counted as an import error). Changing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under."
+          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: {}
@@ -1971,10 +2174,10 @@ components:
           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)."
+          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.
+          description: Shape of the fee structure; the structure field documents the object each one takes.
           enum:
             - FLAT
             - PERCENTAGE
@@ -2231,7 +2434,91 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: "Source-specific configuration object (connection and parsing settings). Optional; defaults to an empty object when omitted. Reserved key duplicate_key: the ordered list of mapped fields that make two rows the same row — any of external_id, amount, currency, date, description, fee_amount, fee_currency. Omit it and rows are deduplicated on external_id alone. A field this source's field map does not fill is refused, because a key over a field that is always empty 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: the aggregator retracts a movement by naming its external id, so that id has to stay this source's row identity. A config holding both is refused in either direction — drop duplicate_key from a bound source, or disconnect the aggregator connection first. Reserved read-only key duplicate_key_changed_at: the RFC 3339 moment duplicate-key detection last changed meaning on this source, set by the server; a value sent by a client is discarded. It moves for either change that re-keys future rows — editing duplicate_key, or the field map remapping the column a declared field reads (a source keyed on description whose description column moves derives a different key for the same movement). Reserved key duplicate_policy: what happens to a row repeating the duplicate key — FLAG_AS_EXCEPTION (the default: the repeat is kept out of the import and raised as a duplicate exception on the row it repeated), KEEP_FIRST (the repeat is dropped and nothing is raised), or REJECT (the repeat is counted as an import error). Changing duplicate_key governs later imports only — rows already imported keep the key they were deduplicated under."
+          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.
@@ -2427,6 +2714,11 @@ components:
         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:
@@ -2440,6 +2732,7 @@ components:
         - volume
         - matchRate
         - sla
+        - unmatchedByCurrency
         - updatedAt
       type: object
     Detail:
@@ -2495,21 +2788,39 @@ components:
       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
@@ -2601,11 +2912,12 @@ components:
       additionalProperties: false
       properties:
         category:
-          description: "Dispute category: BANK_FEE_ERROR (incorrect fee), UNRECOGNIZED_CHARGE, DUPLICATE_TRANSACTION, or OTHER"
+          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
@@ -2765,7 +3077,7 @@ components:
       additionalProperties: false
       properties:
         amount:
-          description: "Enrichment: the exception transaction's amount as a decimal string in the transaction's currency. Present on list rows whose transaction still exists; absent on the get-by-id/resolution paths and when the transaction was deleted."
+          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
@@ -2775,7 +3087,7 @@ components:
             - user@example.com
           type: string
         contextId:
-          description: "Enrichment: id of the reconciliation context the exception's source belongs to (UUID). Present on list rows whose transaction and source still exist; powers the global triage queue's context attribution."
+          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
@@ -2785,7 +3097,7 @@ components:
             - "2025-01-15T10:30:00Z"
           type: string
         currency:
-          description: "Enrichment: ISO 4217 currency code of the exception transaction's amount. Present on list rows whose transaction still exists."
+          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
@@ -2847,6 +3159,9 @@ components:
           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:
@@ -2858,21 +3173,27 @@ components:
             - HIGH
           type: string
         sourceId:
-          description: "Enrichment: id of the reconciliation source the exception transaction belongs to (UUID). Present on list rows whose transaction still exists."
+          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), RESOLVED (closed out)"
+          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 whose transaction still exists."
+          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
@@ -2894,6 +3215,35 @@ components:
         - 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:
@@ -3069,6 +3419,8 @@ components:
           type: string
         status:
           description: Lifecycle status of the queued review (always PENDING_REVIEW on enqueue)
+          enum:
+            - PENDING_REVIEW
           examples:
             - PENDING_REVIEW
           type: string
@@ -3223,6 +3575,10 @@ components:
           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
@@ -3362,7 +3718,7 @@ components:
           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)."
+          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.
@@ -3675,7 +4031,15 @@ components:
       additionalProperties: false
       properties:
         canonicalKey:
-          description: Canonical field-map key the proposal targets
+          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
@@ -3988,9 +4352,13 @@ components:
             - TXN-12345
           type: string
         extractionStatus:
-          description: "Field-extraction status: PENDING (queued), EXTRACTED (fields parsed), FAILED (extraction error)"
+          description: "Field-extraction status: PENDING (queued), COMPLETE (fields parsed), FAILED (extraction error)"
+          enum:
+            - PENDING
+            - COMPLETE
+            - FAILED
           examples:
-            - EXTRACTED
+            - COMPLETE
           type: string
         id:
           description: Unique identifier for the transaction
@@ -4015,9 +4383,14 @@ components:
           format: uuid
           type: string
         status:
-          description: "Matching status: PENDING (not yet evaluated), MATCHED (reconciled), UNMATCHED (no match found)"
+          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:
-            - PENDING
+            - UNMATCHED
           type: string
       required:
         - id
@@ -4060,7 +4433,7 @@ components:
           format: date-time
           type: string
         diagnosis:
-          description: Safe one-line diagnosis for a FAILED job (dialect diagnosis, rate-policy message, or generic safe message); empty for partial completed-with-errors jobs — internal error detail is never surfaced here
+          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
@@ -4137,6 +4510,11 @@ components:
           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
@@ -4207,7 +4585,11 @@ components:
       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"
+          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
@@ -4239,6 +4621,10 @@ components:
       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
@@ -5204,7 +5590,12 @@ components:
             - 550e8400-e29b-41d4-a716-446655440000
           type: string
         status:
-          description: "Current status of the group: PROPOSED (awaiting review), CONFIRMED (accepted), or REJECTED (broken/unmatched)"
+          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
@@ -5263,6 +5654,9 @@ components:
           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
@@ -5421,6 +5815,9 @@ components:
           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
@@ -5488,14 +5885,18 @@ components:
             - 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)"
+          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
-        - type
         - matched
       type: object
     MatchedItemResponse:
@@ -5708,6 +6109,12 @@ components:
           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
@@ -6042,7 +6449,96 @@ components:
           type: string
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings). duplicate_key holds the ordered list of mapped fields that make two rows the same row; absent means rows are deduplicated on external_id alone. duplicate_key_changed_at is the server-set RFC 3339 moment duplicate-key detection last changed meaning on this source — either that list changing, or the field map remapping the column a declared field reads; rows imported before it keep the key they were deduplicated under.
+          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.
@@ -6218,7 +6714,11 @@ components:
             - 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)"
+          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
@@ -6297,6 +6797,10 @@ components:
           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
@@ -6663,7 +7167,9 @@ components:
       required:
         - id
         - status
-      type: object
+      type:
+        - object
+        - "null"
     SetupProgressMatchRulesResponse:
       additionalProperties: false
       properties:
@@ -6725,7 +7231,9 @@ components:
         - method
         - path
         - requiredFields
-      type: object
+      type:
+        - object
+        - "null"
     SetupProgressReadinessResponse:
       additionalProperties: false
       properties:
@@ -7055,6 +7563,11 @@ components:
           type: string
         ruleType:
           description: Strategy of the previewed rule
+          enum:
+            - EXACT
+            - TOLERANCE
+            - DATE_LAG
+            - FUZZY
           examples:
             - EXACT
           type: string
@@ -7102,6 +7615,11 @@ components:
           type: object
         type:
           description: Rule strategy of the inline candidate rule
+          enum:
+            - EXACT
+            - TOLERANCE
+            - DATE_LAG
+            - FUZZY
           examples:
             - EXACT
           type: string
@@ -7368,7 +7886,96 @@ components:
           type: string
         config:
           additionalProperties: {}
-          description: Source-specific configuration object (connection and parsing settings). duplicate_key holds the ordered list of mapped fields that make two rows the same row; absent means rows are deduplicated on external_id alone. duplicate_key_changed_at is the server-set RFC 3339 moment duplicate-key detection last changed meaning on this source — either that list changing, or the field map remapping the column a declared field reads; rows imported before it keep the key they were deduplicated under.
+          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.
@@ -7687,9 +8294,13 @@ components:
             - TXN-12345
           type: string
         extractionStatus:
-          description: "Field-extraction status: PENDING (queued), EXTRACTED (fields parsed), FAILED (extraction error)"
+          description: "Field-extraction status: PENDING (queued), COMPLETE (fields parsed), FAILED (extraction error)"
+          enum:
+            - PENDING
+            - COMPLETE
+            - FAILED
           examples:
-            - EXTRACTED
+            - COMPLETE
           type: string
         id:
           description: Unique identifier for the transaction
@@ -7714,9 +8325,14 @@ components:
           format: uuid
           type: string
         status:
-          description: "Matching status: PENDING (not yet evaluated), MATCHED (reconciled), UNMATCHED (no match found)"
+          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:
-            - PENDING
+            - UNMATCHED
           type: string
       required:
         - id
@@ -7863,34 +8479,27 @@ components:
       additionalProperties: false
       properties:
         accountRef:
-          description: Opaque vendor account reference (Pluggy itemId, Belvo link id) the webhook pull threads onto its request
+          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
-          minLength: 1
           type: string
         baseUrl:
-          description: Vendor API base URL, stored as the connection host
+          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
-          minLength: 1
           type: string
         clientId:
           description: Aggregator API client id (optional; supply with secret to rotate, omit both to keep the stored credential; sealed; never emitted)
           type: string
         configName:
-          description: Unique connection config name (tenant-scoped); the mint endpoint binds a token to this name
+          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
-          minLength: 1
           type: string
         secret:
           description: Aggregator API client secret (optional; supply with clientId to rotate, omit both to keep the stored credential; sealed; never emitted)
           type: string
-      required:
-        - configName
-        - baseUrl
-        - accountRef
       type: object
     UpdateContextRequest:
       additionalProperties: false
@@ -8111,7 +8720,91 @@ components:
       properties:
         config:
           additionalProperties: {}
-          description: "Source-specific configuration object (connection and parsing settings). Reserved key duplicate_key: the ordered list of mapped fields that make two rows the same row — any of external_id, amount, currency, date, description, fee_amount, fee_currency. Send it empty of that key and rows are deduplicated on external_id alone. A field this source's field map does not fill is refused, because a key over a field that is always empty 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: the aggregator retracts a movement by naming its external id, so that id has to stay this source's row identity. A config holding both is refused in either direction — drop duplicate_key from a bound source, or disconnect the aggregator connection first. Editing duplicate_key is allowed at any time and governs later imports only: rows already imported keep the key they were deduplicated under, and a duplicate straddling the change is knowingly not detected. Reserved read-only key duplicate_key_changed_at: the RFC 3339 moment duplicate-key detection last changed meaning on this source, set by the server; a value sent by a client is discarded. It moves for either change that re-keys future rows — editing duplicate_key, or the field map remapping the column a declared field reads (a source keyed on description whose description column moves derives a different key for the same movement). Reserved key duplicate_policy: what happens to a row repeating the duplicate key — FLAG_AS_EXCEPTION (the default: the repeat is kept out of the import and raised as a duplicate exception on the row it repeated), KEEP_FIRST (the repeat is dropped and nothing is raised), or REJECT (the repeat is counted as an import error)."
+          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.
@@ -8386,7 +9079,7 @@ components:
           format: int64
           type: integer
         monthlyLineAllowance:
-          description: Billable lines the plan includes per month, from the price list. Monthly on every plan regardless of billing interval. 0 when the stored plan code is not in the catalogue.
+          description: Billable lines the plan includes per month, from the price list. Monthly on every plan regardless of billing interval. 0 when the plan is unmetered (see volumeUnmetered) or the stored plan code is not in the catalogue.
           format: int64
           type: integer
         overageCreditBalanceCents:
@@ -8394,7 +9087,7 @@ components:
           format: int64
           type: integer
         overageRateCentsPerThousandLines:
-          description: What lines beyond the allowance cost, in integer BRL cents per THOUSAND lines (per-thousand because the entry rate is 0,4 cents a line and would truncate to zero). 0 when the stored plan code is not in the catalogue.
+          description: What lines beyond the allowance cost, in integer BRL cents per THOUSAND lines (per-thousand because the entry rate is 0,4 cents a line and would truncate to zero). 0 when the plan is unmetered (see volumeUnmetered) or the stored plan code is not in the catalogue.
           format: int64
           type: integer
         overageUncoveredCents:
@@ -8411,7 +9104,7 @@ components:
           description: "Setup lifecycle of the workspace: \"provisioning\" (still being built), \"active\" (ready to use), or \"failed\" (setup will not complete on its own — we have been told)."
           type: string
         provisioningStep:
-          description: "The setup step that is owed: \"create_tenant\", \"associate_service\", \"migrate_tenant\", \"provision_console\", or \"\" when nothing is owed. On a failed workspace this is the step it died on."
+          description: "The setup step that is owed: \"create_tenant\", \"associate_service\", \"migrate_tenant\", \"provision_console\", \"grant_admin\", or \"\" when nothing is owed. On a failed workspace this is the step it died on."
           type: string
         trialEndsAt:
           description: When the free trial ends (UTC). Omitted for a paid plan that never trialed.
@@ -8420,6 +9113,9 @@ components:
         trialExpired:
           description: Whether the trial is over on EITHER axis (time or volume), or the workspace is already suspended.
           type: boolean
+        volumeUnmetered:
+          description: "Whether this plan is unmetered: its volume ceiling and its overage price are contractual (enterprise) rather than from the price list. When true, monthlyLineAllowance and overageRateCentsPerThousandLines are both 0 because no figure applies — do NOT render them as terms, and do not read the zero rate as free overage."
+          type: boolean
       required:
         - plan
         - billingStatus
@@ -8432,6 +9128,7 @@ components:
         - provisioningState
         - provisioningStep
         - provisioningFailed
+        - volumeUnmetered
         - monthlyLineAllowance
         - overageRateCentsPerThousandLines
         - overageCreditBalanceCents
@@ -8468,7 +9165,16 @@ info:
     email: support@lerian.studio
     name: Lerian Studio Support
     url: https://discord.gg/DnhqKwkGv3
-  description: Reconciliation engine for the Lerian Studio ecosystem. Provides automated transaction matching between Midaz ledger and external systems.
+  description: |-
+    Reconciliation engine for the Lerian Studio ecosystem. Provides automated transaction matching between Midaz ledger and external systems.
+
+    ## Idempotency
+
+    POST, PUT and PATCH requests accept an optional `Idempotency-Key` header (`X-Idempotency-Key` is also honoured, and wins if both are sent). Keys are 1-128 characters of letters, digits, hyphen, underscore or colon, are scoped per tenant, caller, method and request target, and are strictly opt-in: a request sent without the header is never de-duplicated. A retry under a key whose first attempt completed replays that stored response and carries `Idempotency-Replayed: true`; a retry that arrives while the first attempt is still in flight is refused with 409.
+
+    A request that FAILED normally releases its key, so a caller can correct the cause and retry under the same key. The exception is a dispatch whose outcome could not be confirmed (502, code `MTCH-0514`): the exception may already have been created in the target system, so that answer HOLDS its key — every retry under it replays the same 502 and no second dispatch is sent. Deliberately attempting that dispatch again therefore requires a NEW idempotency key. A dispatch the target answered and rejected (502, code `MTCH-0513`) created nothing there and releases its key as usual.
+
+    Secret mints are the other, sharper exception. `POST /v1/discovery/aggregator-connections/{id}/connect-token`, `POST /v1/discovery/webhooks/tokens`, `POST /v1/exceptions/callbacks/credentials` and `POST /v1/exceptions/callbacks/credentials/{credentialId}/rotate` each return a raw credential exactly ONCE, and storing that answer would keep the secret re-readable for the life of the key — so those four routes IGNORE the idempotency header entirely. Nothing is stored, nothing is replayed, and `Idempotency-Replayed` is never sent on them. A retry under the same key MINTS AGAIN and leaves a second live credential behind, so treat a mint as non-idempotent: read the first attempt's response rather than resending it. A surplus callback credential can be revoked through its own operation; a surplus aggregator webhook token has no revoke operation today and stays live.
   license:
     name: Lerian Studio General License
   title: Matcher Reconciliation API
@@ -8553,6 +9259,43 @@ paths:
       summary: Read a workspace's invoicing identification (backoffice)
       tags:
         - Onboarding
+  /v1/admin/workspaces/{slug}/plan:
+    put:
+      description: "Puts a workspace on the contractual enterprise plan: persists plan=enterprise and billing_status=active together, then evicts the billing edge-gate and volume-resolver caches so the contractual ceiling applies immediately. ONLY \"enterprise\" is accepted. This is not a generic set-plan operation: self-serve plans are bought through hosted checkout and converged from the live subscription's price, so assigning one by hand would be a payment-processor bypass that the next processor delivery silently reverts — any other plan code returns 409. It REFUSES a workspace whose subscription the payment processor could still bill (409): the operator cancels there first, where the proration and refund decision gets human eyes, and this route never moves processor money. That refusal covers every subscription that is not permanently over — one awaiting card authentication or one that is paused is not charging today and resumes tomorrow, and it would revert this plan the moment it does; only a cancelled or expired subscription is assignable over. If the processor cannot be asked, the request is refused as retryable (503) rather than allowed through. A suspended workspace is refused (409) because this operation moves no access posture — reactivate it first, and the write is compare-and-swapped on the status read, so a suspension landing mid-request is refused rather than reversed. There is no reverse: removing the enterprise plan is not offered. The target slug comes from the URL path (backoffice operation, workspace admin action). An unknown workspace returns 404. Errors use RFC 9457 problem+json."
+      operationId: admin-assign-workspace-plan
+      parameters:
+        - description: Slug of the workspace to assign the plan to.
+          in: path
+          name: slug
+          required: true
+          schema:
+            description: Slug of the workspace to assign the plan to.
+            maxLength: 255
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AdminAssignPlanInputBody"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AdminAssignPlanResult"
+          description: OK
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Assign the enterprise plan to a workspace (backoffice)
+      tags:
+        - Onboarding
   /v1/admin/workspaces/{slug}/reactivate:
     put:
       description: "Restores a suspended workspace: persists billing_status=active, re-enables interactive console login at the IdP, reactivates the tenant at the Tenant Manager (best-effort), and evicts the billing edge-gate cache. The target slug comes from the URL path (backoffice operation, workspace admin action). Idempotent. Errors use RFC 9457 problem+json."
@@ -10352,6 +11095,36 @@ paths:
       summary: Update aggregator connection
       tags:
         - Discovery
+  /v1/discovery/aggregator-connections/{id}/connect-token:
+    post:
+      description: "Mints the short-lived token the aggregator vendor's OWN consent widget (Pluggy Connect / the Belvo widget) consumes in the end customer's browser, using the connection's already-sealed credential. The token is returned exactly once: it is never persisted, never logged, and there is no endpoint that reads it back. Nothing is supplied in the request — the vendor is read off the stored connection, and the mode is derived from it: a connection already bound to a vendor item/link gets a RE-CONSENT token for that same item (`reconsent: true`, and `accountRef` echoes the exact item/link the token was scoped to), while a connection awaiting consent gets a first-consent token that mints a new one (`accountRef` empty). Pass the returned `accountRef` to the vendor widget's update mode rather than a locally cached value: the token is item-scoped, and pairing it with a stale id makes the vendor run the create flow and orphan the original item. The item/link id the widget returns is bound back through PUT /v1/discovery/aggregator-connections/{id} with `accountRef` (no credential needs re-supplying). A non-aggregator connection id returns 404; a vendor with no consent path on this deployment returns 422 MTCH-0213."
+      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
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Mint aggregator consent token
+      tags:
+        - Discovery
   /v1/discovery/connections:
     get:
       description: Returns all discovered Fetcher database connections.
@@ -11705,7 +12478,7 @@ paths:
         - Exception
   /v1/exceptions/{exceptionId}:
     get:
-      description: Retrieves a single exception by its ID.
+      description: Retrieves a single exception by its ID, including the amount/currency/date/source/context of its transaction and, for fee breaks, the expected vs credited settlement figures.
       operationId: getException
       parameters:
         - description: Exception ID (UUID)
@@ -13036,7 +13809,10 @@ paths:
         - Governance
   /v1/governance/audit-logs/verify:
     get:
-      description: "Re-verifies the calling tenant's tamper-evident audit hash chain and returns a structured verdict (intact, verified count, and the first broken tenant_seq when a break is found). The check is strictly read-only: it recomputes nothing into storage and never mutates an audit record. Use the optional maxRecords query parameter to bound how many records are inspected."
+      description: |-
+        Re-verifies the calling tenant's tamper-evident audit hash chain and returns a structured verdict (intact, verified count, and the first broken tenant_seq when a break is found). The check is strictly read-only: it recomputes nothing into storage and never mutates an audit record. Use the optional maxRecords query parameter to bound how many records are inspected.
+
+        Use the optional fromSeq query parameter to bind the verification floor: the first record inspected is the one with tenant_seq == fromSeq. A floor above 1 TRUSTS that record's stored prev_hash instead of validating it against the genesis hash, so tampering BELOW the floor is out of scope for that run and is not reported. Two uses follow from that: (1) resuming — when a verdict comes back truncated, re-run with fromSeq = fromSeq + verifiedCount to verify the remainder; (2) archived-partition tenants — once the archival worker has dropped the bottom partitions, verify from the current floor, because a run from seq 1 no longer has the records it would need. The verdict always echoes the effective fromSeq, so an empty range (verifiedCount 0 with a high fromSeq) is never mistaken for an intact chain verified from genesis.
       operationId: verifyAuditLogChain
       parameters:
         - description: Maximum number of records to inspect; clamped to the server bound. Omit to use the default bound.
@@ -13049,6 +13825,15 @@ paths:
             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:
@@ -16378,7 +17163,7 @@ paths:
         - Onboarding
   /v1/workspace/credit-purchase:
     post:
-      description: "Opens a ONE-OFF hosted payment session that buys prepaid overage credit for the AUTHENTICATED tenant's own workspace, and returns the URL to redirect the browser to. It is never a subscription. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers. Any workspace may buy — trialing, lapsed, monthly or annual — because the customer who has run out of allowance is the one being told to buy. Payment is by CARD on every plan, including annual: the instrument that funds overage credit is deliberately not the subscription's instrument, and the card is saved for future CREDIT purchases only. An amount outside the price list's minimum and maximum is refused before the processor is called. The credit balance moves ONLY when the processor confirms the payment through the verified webhook — never on the return page and never in this response. Errors use the RFC 9457 application/problem+json contract."
+      description: "Opens a ONE-OFF hosted payment session that buys prepaid overage credit for the AUTHENTICATED tenant's own workspace, and returns the URL to redirect the browser to. It is never a subscription. The workspace is resolved from the JWT tenant-slug claim: this endpoint never accepts a tenant identifier in the body, path, query or headers. Any workspace on a self-serve plan may buy — trialing, lapsed, monthly or annual — because the customer who has run out of allowance is the one being told to buy. A workspace on a CONTRACTUAL plan is refused with 409: its volume is not metered, so prepaid overage credit buys it nothing. Payment is by CARD on every plan, including annual: the instrument that funds overage credit is deliberately not the subscription's instrument, and the card is saved for future CREDIT purchases only. An amount outside the price list's minimum and maximum is refused before the processor is called. The credit balance moves ONLY when the processor confirms the payment through the verified webhook — never on the return page and never in this response. Errors use the RFC 9457 application/problem+json contract."
       operationId: workspace-credit-purchase
       requestBody:
         content: