> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get the client-level portfolio insight report (BETA)

> > **Beta** — early access.

The client-scope companion of the customer insight report: one deterministic, read-only report over ALL of the caller's customers' agentic activity. Observations (`insights`) and advisory recommendations (`suggestions`) reuse the customer report's item schema — `{kind, severity, message, detail, evidence}` — with two additive fields at this scope: `customer_id` attributes an item to one customer (omitted on cross-customer aggregates, which list the affected customers in `detail`), and `responsibility` is a coarse grouping label (`payment_ops` / `compliance`) for filtering only — it carries no ownership semantics. On top of the items the report adds dashboard-shaped data: KPI `metrics` with previous-window values for trend deltas, daily time `series` for charts, and a per-customer roll-up (`customers`) for drill-down. All query filters are optional and only narrow the report; the response shape never changes. `kind` remains an OPEN set; clients must ignore kinds they do not recognize. Every number is computed server-side on read; nothing is stored, and nothing here moves money or changes state.




## OpenAPI

````yaml /openapi.yaml get /insights
openapi: 3.0.3
info:
  title: Dakota Platform API
  version: 1.0.0
  description: >-
    Combined API specification for Dakota Platform services:

    - Issuance API: Asset minting and burning operations

    - Onboarding API: Know Your Business/Customer verification

    - On/Off Ramp API: Managing on-ramp and off-ramp accounts

    - Recipients API: Managing destinations for KYB'd entities

    - Transactions API: Viewing transaction history across platform operations


    ## Authentication and API Headers


    All API endpoints require the following headers:


    - `x-idempotency-key`: Required for all POST endpoints to ensure request
    idempotency

    - `x-api-key`: Required for authentication across all endpoints


    Note: On /applications endpoints you need a token for authentication instead
    of a x-api-key

    - `x-application-token`: Required for authentication on public /applications
    endpoints (alternative to `x-api-key` where documented)



    ## Rate Limits


    Requests are rate limited per API key. Every response includes the following
    headers:


    | Header | Description |

    | --- | --- |

    | `X-RateLimit-Limit` | Maximum requests allowed in the current one-minute
    window. |

    | `X-RateLimit-Remaining` | Requests remaining in the current window. |

    | `X-RateLimit-Reset` | Absolute Unix timestamp (seconds since epoch) when
    the current rate-limit window resets. |


    When a request is throttled (`429`), responses also include `Retry-After`
    with seconds to wait before retrying.
servers:
  - url: https://api.platform.dakota.xyz
    description: Production environment
  - url: https://api.platform.sandbox.dakota.xyz
    description: Sandbox — safe for testing with simulated data
security:
  - ApiKeyAuth: []
tags:
  - name: Agentic Payments
    x-beta: true
    description: >-
      Beta — agent-driven payments: provision agents, draft and approve spending
      mandates, accept reviewed instructions, and manage scheduled payments.


      **Prerequisites:** Customer onboarded; signer groups attached for
      recognition.

      **Related:** Wallets, Signer Groups, Transactions
  - name: Mandates
    x-beta: true
    description: >-
      Beta — spending mandates: signed, signer-bound authorizations governing
      what may be spent, approved or cancelled by a second recognized signer (§8
      — the dual-control rule that every mandate mutation must be signed by a
      recognized signer OTHER than the bound one). Independent of agents and
      scheduled payments.


      **Prerequisites:** Signer groups attached for recognition.

      **Related:** Signer Groups, Transactions
  - name: Insights
    x-beta: true
    description: >-
      Beta — read-only insight: a deterministic report over a customer's agentic
      activity (funding balances, upcoming obligations, failures, mandate
      headroom and expiry), or — via `GET /insights` — over the whole client's
      book, with portfolio KPIs, daily series and a per-customer roll-up. Never
      moves money, never creates or changes anything.


      **Prerequisites:** Customer onboarded; insight is computed from the
      customer's scheduled payments, mandates, and wallets.

      **Related:** Agentic Payments, Mandates
  - name: Customers
    description: >-
      Manage customer entities representing businesses and organizations
      onboarded to Dakota.


      **Prerequisites:** Complete KYB via Onboarding endpoints before initiating
      money movement.

      **Related:** Onboarding, Recipients, Transactions, Accounts, Wallets
  - name: Wallets
    description: >-
      Manage wallets, balances, and wallet-to-signer-group relationships for
      custody and movement controls.


      **Prerequisites:** Customer must exist. Configure signer groups before
      policy-enforced workflows.

      **Related:** Signer Groups, Policies, Transactions, Customers
  - name: Transactions
    description: >-
      Create, cancel, and retrieve transaction records across account and wallet
      flows.


      **Prerequisites:** Accounts or destinations must be configured based on
      flow type.

      **Related:** Accounts, Recipients, Policies, Events
  - name: Recipients
    description: >-
      Manage recipient entities and destination rails used by customers for
      payouts and transfers.


      **Prerequisites:** Customer must be onboarded and active.

      **Related:** Customers, Transactions, Accounts, Onboarding
  - name: Accounts
    description: >-
      Manage account resources used for onramp, offramp, and swap operations.


      **Prerequisites:** Customer must be created and network/asset constraints
      must be known.

      **Related:** Customers, Transactions, Auto Transactions, Info
  - name: Auto Transactions
    description: >-
      Manage automated transaction configurations and execution history for
      account automation workflows.


      **Prerequisites:** Source account must exist and be configured for
      automation.

      **Related:** Accounts, Transactions, Events
  - name: Onboarding
    description: >-
      Manage KYB/KYC onboarding lifecycle, application documents, attestations,
      and verification steps.


      **Prerequisites:** Customer context and required entity/application
      metadata.

      **Related:** Customers, Exceptions, Recipients, Transactions
  - name: Policies
    description: >-
      Define and manage policy objects and rules used for transaction governance
      and risk controls.


      **Prerequisites:** Wallet and signer group resources should be configured
      for enforcement scenarios.

      **Related:** Wallets, Signer Groups, Transactions
  - name: Signer Groups
    description: >-
      Manage signer groups and signer assignments for multi-party authorization
      models.


      **Prerequisites:** Wallets should exist before linking signer groups.

      **Related:** Wallets, Policies, Transactions
  - name: Authentication
    description: >-
      Manage API authentication credentials and key lifecycle for platform
      access.


      **Prerequisites:** Client organization must be provisioned.

      **Related:** Users, Info
  - name: Users
    description: >-
      Manage client users, roles, and identity metadata for platform access
      control.


      **Prerequisites:** Auth credentials and client context must be
      established.

      **Related:** Authentication
  - name: Webhooks
    description: >-
      Manage outbound webhook targets and delivery configuration for event
      notifications.


      **Prerequisites:** Subscriber endpoint must be reachable and secured.

      **Related:** Events, Authentication
  - name: Payouts
    description: >-
      Manage where Dakota sends your accrued developer-fee payouts.


      **Prerequisites:** Auth credentials and client context must be
      established.

      **Related:** Events
  - name: Events
    description: >-
      Retrieve event records emitted by platform operations for audit and
      troubleshooting.


      **Prerequisites:** Requesting client must have access to referenced
      resources.

      **Related:** Webhooks, Transactions, Onboarding
  - name: Info
    description: >-
      Read platform capability metadata, such as supported rails, networks, and
      assets.

      These operations are served under `/capabilities/*` - `GET
      /capabilities/countries`

      and `GET /capabilities/networks`. The tag name does not appear in the
      request paths.


      **Prerequisites:** Valid authentication headers.

      **Related:** Accounts, Transactions
  - name: Sandbox
    description: >-
      Trigger sandbox-only simulation endpoints for safe end-to-end integration
      testing with synthetic data. The sandbox host
      (`https://api.platform.sandbox.dakota.xyz`) also accepts a family of
      `X-Sandbox-*` request headers on most write endpoints (`Customers`,
      `Accounts`, `Transactions`, simulate endpoints) that let integrators drive
      deterministic failure modes — pick a preset via `X-Sandbox-Scenario`, or
      compose a custom one with
      `X-Sandbox-Error-Step`/`X-Sandbox-Error-Status`/`X-Sandbox-Error-Message`.
      `X-Sandbox-Instant-Completion` collapses async flows to a single
      synchronous step, and `X-Sandbox-Skip-Auto-Approval` keeps newly created
      KYB applications in `pending` for manual-review testing. All `X-Sandbox-*`
      headers are ignored in production.


      **Prerequisites:** Sandbox environment and test customer data.

      **Related:** Customers, Accounts, Transactions, Onboarding
  - name: Legal
    description: |-
      The legal documents customers accept — terms of service, privacy policy,
      e-sign notice, and partner agreements.

      Dakota publishes these here, and this is the authoritative source: the
      hosted onboarding flow, the dakota.xyz website, and your own integration
      all read the same revisions. Present the current revision to your customer
      before capturing their acceptance so the record reflects the text they
      actually saw.
paths:
  /insights:
    get:
      tags:
        - Insights
      summary: Get the client-level portfolio insight report (BETA)
      description: >
        > **Beta** — early access.


        The client-scope companion of the customer insight report: one
        deterministic, read-only report over ALL of the caller's customers'
        agentic activity. Observations (`insights`) and advisory recommendations
        (`suggestions`) reuse the customer report's item schema — `{kind,
        severity, message, detail, evidence}` — with two additive fields at this
        scope: `customer_id` attributes an item to one customer (omitted on
        cross-customer aggregates, which list the affected customers in
        `detail`), and `responsibility` is a coarse grouping label
        (`payment_ops` / `compliance`) for filtering only — it carries no
        ownership semantics. On top of the items the report adds
        dashboard-shaped data: KPI `metrics` with previous-window values for
        trend deltas, daily time `series` for charts, and a per-customer roll-up
        (`customers`) for drill-down. All query filters are optional and only
        narrow the report; the response shape never changes. `kind` remains an
        OPEN set; clients must ignore kinds they do not recognize. Every number
        is computed server-side on read; nothing is stored, and nothing here
        moves money or changes state.
      operationId: getClientInsights
      parameters:
        - name: customer_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Scope the whole report to one customer (drill-down). An unknown or
            foreign customer is a 404, mirroring the customer report.
        - name: wallet_id
          in: query
          required: false
          schema:
            type: string
          description: Keep only items whose evidence references this wallet.
        - name: kind
          in: query
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
          description: >-
            Keep only items of these kinds (comma-separated, e.g.
            `kind=volume_anomaly,recipient_dormant`; open set — an unrecognized
            value simply matches nothing).
        - name: severity
          in: query
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              x-extensible-enum:
                - info
                - warn
                - critical
          description: >
            Keep only items of these severities (comma-separated, e.g.
            `severity=critical,warn`). Values are `info`, `warn`, `critical`;
            anything else is a 400.
        - name: responsibility
          in: query
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              x-extensible-enum:
                - payment_ops
                - compliance
          description: >-
            Keep only items carrying one of these grouping labels
            (comma-separated).
        - name: window_days
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 90
            default: 14
          description: >-
            Report window in days — the lookback for trends/series and the
            horizon for upcoming obligations.
      responses:
        '200':
          description: The client's portfolio insight report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientInsightReport'
              example:
                generated_at: 1788337300
                window_days: 14
                snapshot:
                  customers:
                    total: 42
                    scanned: 42
                    with_activity: 17
                    with_critical: 2
                  total_usd: '1284500.00'
                  upcoming:
                    days: 14
                    count: 31
                    totals:
                      USDC: '412600'
                  open_scheduled_payments: 44
                  active_mandates: 57
                  metrics:
                    - key: executed_volume
                      label: Executed volume
                      asset: USDC
                      value: '861200'
                      previous: '702300'
                      change_pct: '22.6'
                    - key: failed_payments
                      label: Payments failed
                      value: '9'
                      previous: '3'
                      change_pct: '200.0'
                series:
                  bucket: day
                  from: 1787097600
                  to: 1789516800
                  metrics:
                    failed_payments:
                      - t: 1787097600
                        v: '0'
                      - t: 1787184000
                        v: '3'
                    executed_volume.USDC:
                      - t: 1787097600
                        v: '41200'
                      - t: 1787184000
                        v: '63800'
                facets:
                  kinds:
                    - mandate_expiring
                    - payment_failures_clustered
                    - recipient_dormant
                  severities:
                    - info
                    - warn
                  responsibilities:
                    - compliance
                    - payment_ops
                  assets:
                    - USDC
                insights:
                  - kind: payment_failures_clustered
                    severity: warn
                    responsibility: payment_ops
                    message: >-
                      7 payments across 2 customers failed in the last 14 days
                      with the same failure code: mandate_denied (e.g.
                      "transaction denied by mandate: amount 5000 exceeds
                      max_per_tx 2500").
                    detail:
                      count: 7
                      window_days: 14
                      failure_code: mandate_denied
                      failure_reason: >-
                        transaction denied by mandate: amount 5000 exceeds
                        max_per_tx 2500
                      docs_url: >-
                        https://docs.dakota.xyz/documentation/agentic-payments/webhooks#failure_code-reference
                      customer_ids:
                        - 2vWxCustomer0000000000000000
                        - 2vWxCustomer0000000000000001
                    evidence:
                      - type: scheduled_payment
                        id: 2vWxPayment00000000000000000
                  - kind: recipient_dormant
                    severity: info
                    responsibility: compliance
                    customer_id: 2vWxCustomer0000000000000000
                    message: >-
                      Recipient "Northwind Ltd" hasn't been paid in 123 days
                      (last payment 2026-05-02, 14 payment(s) before that).
                    detail:
                      recipient_id: 2vWxRecipient000000000000000
                      recipient_name: Northwind Ltd
                      days_since_last_use: 123
                      last_used_at: 1777500000
                      prior_payments: 14
                    evidence:
                      - type: recipient
                        id: 2vWxRecipient000000000000000
                suggestions:
                  - kind: mandate_expiring
                    severity: warn
                    responsibility: payment_ops
                    customer_id: 2vWxCustomer0000000000000000
                    message: >-
                      Mandate for USDC on base expires in 6 day(s) (2026-09-07).
                      3 open scheduled payment(s) depend on it. Mandates are
                      immutable — a replacement needs a new signature.
                    detail:
                      mandate_id: 2vWxMandate00000000000000000
                      days_left: 6
                      valid_until: 1788855700
                      dependent_payments: 3
                    evidence:
                      - type: mandate
                        id: 2vWxMandate00000000000000000
                customers:
                  - customer_id: 2vWxCustomer0000000000000000
                    name: Acme Robotics
                    total_usd: '84200.00'
                    open_scheduled_payments: 6
                    active_mandates: 4
                    upcoming:
                      days: 14
                      count: 5
                      totals:
                        USDC: '9400'
                    item_counts:
                      critical: 1
                      warn: 1
                      info: 1
                    last_activity_at: 1788310000
        '400':
          description: Invalid request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: >-
                  https://docs.dakota.xyz/api-reference/errors#invalid-identifier
                title: Invalid Identifier
                status: 400
                detail: invalid customer id
        '404':
          description: >-
            Agentic payments not enabled, or the customer_id filter names an
            unknown customer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://docs.dakota.xyz/api-reference/errors#not-found
                title: Not Found
                status: 404
                detail: agentic payments are not enabled
components:
  schemas:
    ClientInsightReport:
      type: object
      required:
        - generated_at
        - window_days
        - snapshot
        - series
        - facets
        - insights
        - suggestions
        - customers
      description: >
        The deterministic, read-only portfolio insight report for the calling
        client. Computed on demand across the client's own customers (never
        cross-tenant); nothing is stored.
      properties:
        generated_at:
          type: integer
          format: int64
        window_days:
          type: integer
        snapshot:
          $ref: '#/components/schemas/ClientInsightSnapshot'
        facets:
          $ref: '#/components/schemas/ClientInsightFacets'
        series:
          $ref: '#/components/schemas/ClientInsightSeries'
        insights:
          type: array
          items:
            $ref: '#/components/schemas/InsightItem'
          description: Observations across the book (always present, possibly empty).
        suggestions:
          type: array
          items:
            $ref: '#/components/schemas/InsightItem'
          description: >-
            Advisory recommendations (always present, possibly empty).
            Non-binding — acting on one is a separate, human-gated step.
        customers:
          type: array
          items:
            $ref: '#/components/schemas/ClientInsightCustomer'
          description: >-
            Per-customer roll-up for the drill-down table, sorted worst-first
            (critical count, then warn, then activity).
    ProblemDetails:
      type: object
      required:
        - type
        - title
        - status
      description: |
        Error response following RFC 9457 Problem Details.
        Public API error responses use this format.
      example:
        type: https://docs.dakota.xyz/api-reference/errors#not-found
        title: Customer Not Found
        status: 404
        detail: Customer cst_2abc123 was not found in your organization.
        instance: https://api.platform.dakota.xyz/customers/cst_2abc123
        request_id: req_7f3a8b2c
      properties:
        type:
          type: string
          format: uri
          description: |
            URI reference identifying the problem type.
            Resolves to human-readable documentation.
          example: https://docs.dakota.xyz/api-reference/errors#not-found
        title:
          type: string
          description: >-
            Short, human-readable summary of the problem type. Stable across
            occurrences.
          example: Customer Not Found
        status:
          type: integer
          description: HTTP status code for this occurrence.
          example: 404
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          example: Customer cst_2abc123 was not found in your organization.
        instance:
          type: string
          format: uri
          description: The request path that triggered this error.
          example: https://api.platform.dakota.xyz/customers/cst_2abc123
        request_id:
          type: string
          description: Unique request identifier. Include when contacting support.
          example: req_7f3a8b2c
        errors:
          type: array
          description: Field-level validation errors (present for validation failures).
          items:
            $ref: '#/components/schemas/ValidationError'
        resolution_url:
          type: string
          format: uri
          description: |
            A link the customer can follow to CLEAR this error, present only on
            problems with a concrete self-service remedy.

            Today this is returned by
            `#terms-not-accepted`, where it points at the hosted flow in which
            the outstanding agreement can be signed. The link is token-gated and
            usable as-is — send the customer to it directly rather than parsing
            it out of `detail`.
          example: >-
            https://onboarding.dakota.xyz/applications/2abc123?token=tok_7f3a8b2c
        user_message:
          type: string
          description: |
            A plain-language rendition of `detail` written for the end
            customer, present when one exists for this error. `detail` names
            request fields and actions so a machine caller (such as a payment
            agent drafting proposals) can self-correct; `user_message` says the
            same thing without API vocabulary. Clients that relay errors into a
            human surface (chat, email, UI) should show `user_message` when
            present and fall back to `detail`.
          example: >-
            ACH payments pay out USD, so a USDC payout isn't possible on this
            rail. Change the payout currency to USD and try again.
    ClientInsightSnapshot:
      type: object
      required:
        - customers
        - upcoming
        - open_scheduled_payments
        - active_mandates
        - metrics
      description: >
        Typed FACTS about the client's whole book — rendered directly, not
        narrated. `total_usd` covers indexed funding-wallet balances and is
        present only when the balance index is configured; it degrades to
        absent, never to an error. `balances` (per wallet × asset) is present
        only when the report is scoped to one customer (`?customer_id=`), so a
        drill-down can show that customer's holdings overall, by asset and by
        wallet.
      properties:
        customers:
          $ref: '#/components/schemas/ClientInsightCustomersSummary'
        total_usd:
          type: string
        balances:
          type: array
          items:
            $ref: '#/components/schemas/InsightSnapshotBalance'
        upcoming:
          $ref: '#/components/schemas/InsightSnapshotUpcoming'
        open_scheduled_payments:
          type: integer
        active_mandates:
          type: integer
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/ClientInsightMetric'
    ClientInsightFacets:
      type: object
      required:
        - kinds
        - severities
        - responsibilities
        - assets
      description: >
        The values present in the report BEFORE the item filters (`kind`,
        `severity`, `responsibility`) were applied — so a UI can offer every
        option a client could pick even while a filter is active. `assets` are
        the assets moving in the window (metrics + series).
      properties:
        kinds:
          type: array
          items:
            type: string
        severities:
          type: array
          items:
            type: string
        responsibilities:
          type: array
          items:
            type: string
        assets:
          type: array
          items:
            type: string
    ClientInsightSeries:
      type: object
      required:
        - bucket
        - from
        - to
        - metrics
      description: >
        Daily time series for charts. Map keys are an OPEN set named `<metric>`
        for counts and `<metric>.<ASSET>` for amounts — emitted today:
        `executed_payments`, `failed_payments`, `executed_volume.<ASSET>`
        (lookback over the report window) and `upcoming_obligations.<ASSET>`
        (forward-looking: open payments due per day from now through the next
        `window_days`; an OVERDUE open payment is not plotted here — it is
        counted in `snapshot.upcoming`, which spans everything due through the
        horizon, and surfaces as a `payment_at_risk` item). Clients must ignore
        keys they do not recognize.
      properties:
        bucket:
          type: string
          enum:
            - day
        from:
          type: integer
          format: int64
          description: Start of the earliest bucket (unix seconds).
        to:
          type: integer
          format: int64
          description: End of the latest bucket (unix seconds).
        metrics:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ClientInsightSeriesPoint'
    InsightItem:
      type: object
      required:
        - kind
        - severity
        - message
        - evidence
      description: >
        One observation (in `insights`) or advisory recommendation (in
        `suggestions`) — the same schema in both arrays. `kind` is an OPEN set:
        new kinds appear without notice and clients must ignore kinds they do
        not recognize.
      properties:
        kind:
          type: string
          description: >
            Machine-readable item type. This is an OPEN set — the values below
            are the kinds emitted TODAY, but new kinds may be added at any time
            without a breaking change, so it is documented as an extensible enum
            rather than a closed one. A client MUST render an unrecognized kind
            generically from `message` + `severity` (and `evidence`), never drop
            it. Kinds emitted today, by array:

            Observations (`insights[]`):
              * `upcoming_payments` — open payments due within the horizon (count + per-asset totals).
              * `payment_failures_clustered` — ≥2 recent failures to the same payee sharing one reason (root cause). `detail` carries `failure_reason`, `failure_code` (the documented stable code, when the reason classifies) and `docs_url` (the published failure_code reference).
              * `payments_failed` — remaining recent singleton failures, summarized (`detail.docs_url` links the reference).
              * `account_activity` — executed volume over the window + mandates awaiting signature.
              * `new_counterparty` — first open payments to a recently-added payee.
              * `counterparty_concentration` — one payee dominates recent executed outflow.

            Suggestions (`suggestions[]`, advisory — acting is a separate
            human-gated step):
              * `payment_at_risk` — an open payment is past its scheduled time.
              * `funding_shortfall` — a funding wallet's indexed balance is below its near-term payment needs.
              * `mandate_expiring` — an active mandate ends soon (warn when open payments depend on it).
              * `mandate_headroom` — a mandate's window budget is nearly or already over-consumed.

            Kinds emitted only by the client-level report (`GET /insights`)
            today:
              * `volume_anomaly` — a customer's executed volume is a large multiple of that customer's own baseline (observation).
              * `recipient_dormant` — a previously-paid recipient has gone unpaid for a long stretch (observation; `detail` carries `days_since_last_use` and `last_used_at`).
          x-extensible-enum:
            - upcoming_payments
            - payment_failures_clustered
            - payments_failed
            - account_activity
            - new_counterparty
            - counterparty_concentration
            - payment_at_risk
            - funding_shortfall
            - mandate_expiring
            - mandate_headroom
            - volume_anomaly
            - recipient_dormant
        severity:
          type: string
          enum:
            - info
            - warn
            - critical
        message:
          type: string
          description: >-
            Human-readable, self-contained statement of the finding, with exact
            amounts and dates.
        detail:
          type: object
          additionalProperties: true
          description: >-
            Machine-readable facts behind the message (decimal strings, counts,
            unix timestamps). Keys vary by kind.
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/InsightEvidence'
          description: >-
            The platform objects this item is computed from (capped; may be
            empty when the claim is an aggregate).
        customer_id:
          type: string
          description: >
            Client-level report only — the customer this item is about. Omitted
            on cross-customer aggregates (which list the affected customers in
            `detail`) and on the customer report, where the scope is the path.
        responsibility:
          type: string
          description: >
            Client-level report only — a coarse grouping label for routing and
            filtering (which "department" cares). A label, not ownership: it
            reuses the insight-agent responsibility catalog names so a future
            entity build can adopt them without a contract change.
          x-extensible-enum:
            - payment_ops
            - compliance
    ClientInsightCustomer:
      type: object
      required:
        - customer_id
        - open_scheduled_payments
        - active_mandates
        - upcoming
        - item_counts
      description: >
        One customer's roll-up row for the drill-down table. Re-query with
        `?customer_id=` (or the customer report) for the full picture.
      properties:
        customer_id:
          type: string
        name:
          type: string
        total_usd:
          type: string
          description: >-
            Indexed funding-wallet balance in USD. Present only when the balance
            index is configured.
        open_scheduled_payments:
          type: integer
        active_mandates:
          type: integer
        upcoming:
          $ref: '#/components/schemas/InsightSnapshotUpcoming'
        item_counts:
          $ref: '#/components/schemas/ClientInsightItemCounts'
        last_activity_at:
          type: integer
          format: int64
          description: >-
            Unix seconds of the customer's most recent executed payment in the
            lookback. Omitted when there is none.
    ValidationError:
      type: object
      required:
        - field
        - message
      properties:
        field:
          type: string
          description: Field path using dot notation for nested fields.
          example: bank_account.routing_number
        message:
          type: string
          description: Human-readable description of the field error.
          example: Routing number must be exactly 9 digits
        code:
          type: string
          description: Machine-readable error code for this field.
          example: invalid_format
    ClientInsightCustomersSummary:
      type: object
      required:
        - total
        - scanned
        - with_activity
        - with_critical
      description: >
        The customer population behind the report. `scanned < total` means the
        report hit its per-request scan cap (100) and was computed over a prefix
        of the book in the customer list's order (name, then id) — truncation is
        never silent. `with_activity` counts customers with any non-cancelled
        scheduled payment or report item, not only inside the window.
      properties:
        total:
          type: integer
        scanned:
          type: integer
        with_activity:
          type: integer
        with_critical:
          type: integer
    InsightSnapshotBalance:
      type: object
      required:
        - wallet_id
        - network_id
        - asset
        - amount_usd
      description: >-
        One funding wallet's indexed holding of one asset on one network. The
        balance index prices holdings in USD; values may lag the chain.
      properties:
        wallet_id:
          type: string
        name:
          type: string
        network_id:
          type: string
        asset:
          type: string
        amount_usd:
          type: string
    InsightSnapshotUpcoming:
      type: object
      required:
        - days
        - count
      description: Open scheduled payments due within the window.
      properties:
        days:
          type: integer
        count:
          type: integer
        totals:
          type: object
          additionalProperties:
            type: string
          description: Asset → total amount due in the window (decimal strings).
    ClientInsightMetric:
      type: object
      required:
        - key
        - label
        - value
      description: >
        One portfolio KPI over the report window, paired with the previous
        window's value so a dashboard can render a trend delta (value + change
        vs the prior period). Amount metrics repeat per asset with `asset` set;
        count metrics omit it. `key` is an OPEN set like `kind`.
      properties:
        key:
          type: string
          description: >
            Machine-readable metric name. Open set — emitted today are
            `executed_volume` (per asset), `executed_payments`,
            `failed_payments` and `new_counterparties`.
          x-extensible-enum:
            - executed_volume
            - executed_payments
            - failed_payments
            - new_counterparties
        label:
          type: string
          description: Human-readable metric name for direct rendering.
        asset:
          type: string
          description: >-
            Set on amount metrics (one metric entry per asset); absent on
            counts.
        value:
          type: string
          description: Decimal string — the metric over the report window.
        previous:
          type: string
          description: >-
            Decimal string — the same metric over the window immediately before
            the report window.
        change_pct:
          type: string
          description: >-
            Decimal string, signed — percent change vs `previous`. Omitted when
            `previous` is zero.
    ClientInsightSeriesPoint:
      type: object
      required:
        - t
        - v
      description: One bucket of a time series.
      properties:
        t:
          type: integer
          format: int64
          description: Bucket start (unix seconds, UTC).
        v:
          type: string
          description: Decimal string — the bucket's value.
    InsightEvidence:
      type: object
      required:
        - type
        - id
      description: >-
        One typed reference to the platform object an insight item was computed
        from.
      properties:
        type:
          type: string
          description: >
            Platform resource name — the kind of object `id` refers to. OPEN set
            (like `InsightItem.kind`): new resource types may be referenced
            without a breaking change, so a client MUST handle an unrecognized
            type gracefully (e.g. show the item without a deep-link), never
            error. `transaction` is reserved (advertised and client-handled, but
            not emitted today).
          x-extensible-enum:
            - wallet
            - scheduled_payment
            - mandate
            - recipient
            - transaction
        id:
          type: string
    ClientInsightItemCounts:
      type: object
      required:
        - critical
        - warn
        - info
      description: >-
        How many report items (insights + suggestions) reference the customer,
        by severity.
      properties:
        critical:
          type: integer
        warn:
          type: integer
        info:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````